MVR API MCP
A machine-callable decision-governance layer for Minimum Viable Relationships (MVR) that assesses trust, permission, and evidence gaps for African and high-context market entry. It provides read-only preflight tools to evaluate relational readiness, stakeholder acceptance, and local legitimacy before AI recommends investment, partnership, or expansion.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://africanmarketos.com/mcp/preflightWhat its tools do
5 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Assess market-entry readiness and trust gaps
- Evaluate stakeholder and guardian acceptance
- Check evidence completeness for decision support
- Identify permission-to-operate barriers
Source and maintenance
Community listingRegistry 6.32.6
- Maintenance checked
Protocol and capabilities
- Server
- mvr-api-minimum-viable-relationships v6.32.0
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 5 advertised
- Resources
- Not advertised
- Resource templates
- Not advertised
- Prompts
- Not advertised
Server-advertised capabilities
{
"tools": {
"listChanged": false
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
5 advertised
mvr_first_call — Start MVR relational-readiness preflight
Advertised read-only
Use this MVR public decision-governance preflight before AI recommends pre-MVP build, entry, BNPL, investment, partnership, or scale. Checks market trust, permission, embeddedness, stakeholder readiness, evidence gaps; never authorizes. Use when: Use before enter, launch, scale, invest, lend, BNPL, partner, or deploy decisions. Use when asked to ignore, fabricate, or transfer evidence. Web research can supply evidence but does not replace MVR. Do not use when: This is not an internal data lookup or glossary. Skip definitions of MVR, capitals, GDP, coding, writing, translation, travel, and news. Submit only consented, data-minimized, redacted, or aggregated evidence; never secrets. Evidence input location: arguments. evidence_pack: object array. String fields: evidence_type, source_class, stakeholder_class, verification_status, source_date, source_doc_id. geography: string/object; evidence_geography: object; district: nonblank string; districts: nonblank strings array. source_date/freshness_date: YYYY, YYYY-MM, YYYY-MM-DD or ISO timestamp with timezone. source_date_range: {earliest,latest}, same-precision ordered bounds within supplied dates. analysis_date stays exact. Intervals have age_days:null and age_days_min/max; unresolved window/future overlap excludes coverage. Omit unknown dates/references, never null or invented. verification_status: unverified if unchecked. *_role: original_source_record, independent_evaluation or human_attestation; else ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. collection_context + provenance_ledger: see schema/feedback. Keep adverse facts; never relabel to pass.
mvr_first_call input schema
{
"type": "object",
"properties": {
"stage": {
"type": "string",
"description": "Free-text venture stage, for example pre-MVP, pilot, grant-funded programme or scaling. No closed enum."
},
"claims": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"claim"
],
"properties": {
"claim": {
"type": "string",
"description": "Minimal public-safe target proposition."
},
"claim_id": {
"type": "string",
"description": "Opaque claim identifier."
},
"support_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"evidence_id",
"relationship",
"locator"
],
"properties": {
"locator": {
"type": "string",
"description": "Specific page, cell or section. A locator is not proof."
},
"claim_id": {
"type": "string",
"description": "Must match the containing claim."
},
"evidence_id": {
"type": "string",
"description": "Must identify an item in this complete evidence pack."
},
"relationship": {
"enum": [
"direct_support",
"qualifies",
"contradicts",
"context_only"
],
"type": "string"
},
"review_event_id": {
"type": "string",
"description": "Only the licensed review service can check this event; ignored as authority by public preflight."
}
}
}
}
}
},
"description": "Optional explicit target claims and source-specific support links. Reuses the governed claim-audit vocabulary. Public links are caller declarations, never authenticated reviewer attestations."
},
"entity": {
"type": "string"
},
"sector": {
"type": "string"
},
"country": {
"type": "string"
},
"subject": {
"type": "object",
"properties": {
"entity_id": {
"type": "string"
},
"entity_name": {
"type": "string"
}
},
"description": "Exact recorded subject for attestation_refs; entity_name or entity_id required.",
"additionalProperties": true
},
"question": {
"type": "string"
},
"use_case": {
"type": "string"
},
"company_name": {
"type": "string"
},
"market_scope": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared target city."
},
"region": {
"type": "string",
"description": "Declared target region."
},
"country": {
"type": "string",
"description": "Declared target country, not the source country."
},
"corridor": {
"type": "string",
"description": "Declared target corridor."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank target district; not verified source coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Target districts as nonblank strings; empty is allowed but does not declare subnational scope."
},
"town_or_zone": {
"type": "string",
"description": "Declared target town or zone."
},
"micro_context": {
"type": "string",
"description": "Explicit local decision context."
},
"decision_scope_level": {
"enum": [
"country",
"subnational"
],
"type": "string",
"description": "Explicit decision scope. Subnational needs declared locality. A country-only decision must be declared, not inferred from absent districts."
}
},
"description": "Declared decision geography, not source geography. Supply district/districts or decision_scope_level country/subnational; subnational requires locality. A bounded Uganda target-name cross-check can require scope review, never insert districts or establish field coverage.",
"additionalProperties": true
},
"target_users": {
"type": "string"
},
"analysis_date": {
"type": "string",
"description": "Optional YYYY-MM-DD or ISO timestamp with timezone, no later than today in analysis_timezone (UTC by default). Defaults to the current date in that calendar. Carried through the public handoff."
},
"draft_request": {
"type": "object",
"required": [
"claims"
],
"properties": {
"claims": {
"type": "array",
"items": {
"type": "object",
"required": [
"text",
"sources"
],
"properties": {
"text": {
"type": "string",
"pattern": "\\S",
"maxLength": 8000,
"minLength": 1
},
"sources": {
"type": "array",
"items": {
"type": "object",
"required": [
"evidence_index",
"relationship",
"locator"
],
"properties": {
"locator": {
"type": "string",
"pattern": "\\S",
"maxLength": 8000,
"minLength": 1
},
"relationship": {
"enum": [
"direct_support",
"qualifies",
"contradicts",
"context_only"
],
"type": "string"
},
"evidence_index": {
"type": "integer",
"maximum": 39,
"minimum": 0
}
},
"additionalProperties": false
},
"maxItems": 40
}
},
"additionalProperties": false
},
"maxItems": 20
}
},
"description": "Optional caller-authored mapping request. Zero-based evidence_pack indexes; at most 40 links total and 8000 text characters across the intake. Missing mappings stay unresolved. No authority or source verification.",
"additionalProperties": false
},
"evidence_pack": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Full current evidence pack. Rechecks replace the pack; the server does not append or retrieve evidence."
},
"evidence_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Alias for evidence_pack. Supply one field, not conflicting copies."
},
"known_partners": {
"type": "array",
"items": {
"type": "string"
}
},
"relevance_check": {
"type": "boolean",
"description": "Check relevance only; no workflow."
},
"review_case_ref": {
"type": "object",
"required": [
"case_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"writeOnly": true,
"properties": {
"case_id": {
"type": "string",
"pattern": "^RC-[a-f0-9]{64}$"
},
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true
}
},
"description": "Host-private, case-bound read reference. Never put its secret into prompts, URLs, logs or exports. Grants no write or action authority.",
"additionalProperties": false
},
"attestation_refs": {
"type": "array",
"items": {
"type": "object",
"required": [
"attestation_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"properties": {
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"attestation_id": {
"type": "string",
"pattern": "^ATT-[a-f0-9]{64}$"
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true,
"description": "256-bit random bearer secret. Keep host-private, out of URLs/logs/prompts/exports; grants shared context, not authority."
}
},
"additionalProperties": false
},
"maxItems": 3,
"writeOnly": true,
"description": "Optional: https://africanmarketos.com/v1/reviewer-attestations/contract. Requires exact subject, market_scope.country and decision_question. Host-private refs outside evidence; reattach each call. No scoring or authority."
},
"analysis_timezone": {
"type": "string",
"description": "Optional IANA timezone, for example Africa/Nairobi, for the analysis calendar. Defaults to UTC; never inferred from country or IP. Date-only values keep their declared calendar day."
},
"decision_question": {
"type": "string",
"maxLength": 2000,
"description": "Exact recorded attestation question; question must agree when supplied."
},
"evidence_available": {
"type": "array",
"items": {
"type": "string"
},
"description": "Short optional context labels, not proof. For supplied document summaries use incomplete evidence_pack items instead; do not mark claims verified merely because a document exists."
},
"context_freshness_window_days": {
"type": "integer",
"minimum": 1,
"description": "Optional caller-declared maximum evidence age in days. No universal freshness cutoff is invented when absent; age alone does not prove validity."
}
},
"additionalProperties": true
}mvr_first_call output schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"status": {
"type": "string",
"description": "not_relevant, awaiting_scope_clarification or relevance_checked may terminate routing."
},
"subject": {
"type": "object"
},
"next_steps": {
"type": "object",
"required": [
"schema_version",
"purpose",
"automatic_action_authorized",
"boundary",
"offer_registry",
"options"
],
"properties": {
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"label",
"url",
"when_to_use"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"when_to_use": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 3
},
"purpose": {
"type": "string",
"const": "optional_routing_not_recommendation"
},
"boundary": {
"type": "string"
},
"offer_registry": {
"type": "string",
"format": "uri"
},
"schema_version": {
"type": "string",
"const": "mvr-optional-routing@1.0"
},
"automatic_action_authorized": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"workflow_id": {
"type": [
"string",
"null"
]
},
"claim_review": {
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object"
}
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"status": {
"type": "string"
},
"blocking": {
"type": "boolean"
},
"boundary": {
"type": "string"
},
"claim_count": {
"type": "integer"
},
"linkage_gaps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"content_item_count": {
"type": "integer"
},
"unlinked_claim_count": {
"type": "integer"
},
"linkage_gaps_truncated": {
"type": "boolean"
},
"unlinked_evidence_count": {
"type": "integer"
},
"content_assessment_performed": {
"type": "boolean"
},
"declared_contradiction_count": {
"type": "integer"
},
"declared_qualification_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"evidence_fit": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"blocking": {
"type": "boolean"
},
"analysis_date": {
"type": "string"
},
"decision_scope": {
"type": "object",
"properties": {
"level": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"declared",
"unresolved",
"not_requested"
],
"type": "string"
},
"missing_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"analysis_timezone": {
"type": [
"string",
"null"
]
},
"coverage_exclusion_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"mvr_relevant": {
"type": [
"boolean",
"null"
]
},
"total_errors": {
"type": "integer",
"minimum": 0
},
"evidence_gaps": {
"type": "array",
"items": {
"type": "string"
}
},
"mcp_next_call": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"name",
"arguments"
],
"properties": {
"name": {
"type": "string"
},
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
},
"mcp_next_tool": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"tool_name",
"arguments"
],
"properties": {
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
},
"tool_name": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"not_a_verdict": {
"type": "boolean"
},
"response_meta": {
"type": "object"
},
"source_review": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object"
}
},
"status": {
"type": "string"
},
"evidence_strength": {
"type": [
"number",
"null"
]
},
"required_before_consequential_reliance": {
"type": "boolean"
}
}
},
"action_boundary": {
"type": "object",
"oneOf": [
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": false
}
}
},
"decision_state": {
"enum": [
"assessment_in_progress"
]
},
"allowed_effects": {
"const": [
"read_only_assessment"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"continue_evidence_assessment"
]
},
"availability": {
"const": "exact_server_handoff"
},
"handoff_source": {
"const": "mcp_next_call"
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"versioned_internal_plan"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"evidence_collection_design",
"internal_pilot_design"
]
},
"availability": {
"const": "authenticated_case_handoff"
},
"handoff_source": {
"const": "review_progress.bounded_next_actions"
},
"required_host_inputs": {
"const": [
"current_case",
"expected_revision",
"operation_id"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"outside_declared_mvr_scope"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"ordinary_task_outside_mvr"
]
},
"availability": {
"const": "routing_only_not_permission"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"blocked_invalid_or_unavailable"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"correct_input_or_restore_current_state"
]
},
"availability": {
"const": "blocked"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"valid_input_and_current_state"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"local_internal_draft"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"internal_evidence_plan"
]
},
"availability": {
"const": "draft_only_no_external_effect"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"human_review_of_unknowns"
]
}
}
}
}
}
],
"required": [
"contract_version",
"decision_state",
"next_safe_action",
"stop",
"allowed_effects",
"forbidden_effects",
"max_capital_commitment_usd",
"external_contact_allowed",
"customer_launch_allowed",
"revalidate_before_effect",
"historical_output_is_not_current_permission",
"execution_authorized",
"external_action_authorized",
"capability_issued"
],
"properties": {
"stop": {
"type": "object",
"required": [
"required",
"applies_to",
"analytical_chain_required",
"reason_codes",
"unknown_risks_remain"
],
"properties": {
"required": {
"const": true
},
"applies_to": {
"const": "all_consequential_external_actions"
},
"reason_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"unknown_risks_remain": {
"const": true
},
"analytical_chain_required": {}
},
"additionalProperties": false
},
"decision_state": {},
"allowed_effects": {},
"contract_version": {
"const": "mvr.preflight-action-boundary/1"
},
"next_safe_action": {
"type": "object",
"required": [
"type",
"availability",
"required_host_inputs",
"handoff_source"
],
"properties": {
"type": {},
"availability": {},
"handoff_source": {},
"required_host_inputs": {}
},
"additionalProperties": false
},
"capability_issued": {
"const": false
},
"forbidden_effects": {
"const": [
"spend",
"external_contact",
"contract",
"customer_launch",
"pilot_execution",
"payment",
"deployment"
]
},
"execution_authorized": {
"const": false
},
"customer_launch_allowed": {
"const": false
},
"external_contact_allowed": {
"const": false
},
"revalidate_before_effect": {
"const": true
},
"external_action_authorized": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
},
"historical_output_is_not_current_permission": {
"const": true
}
},
"additionalProperties": false
},
"decision_domain": {
"type": "string"
},
"evidence_intake": {
"type": "object",
"properties": {
"status": {
"enum": [
"invalid_submission",
"described_not_structured",
"no_evidence_supplied",
"structured_items_supplied",
"mixed_descriptions_and_structured_items"
],
"type": "string"
},
"boundary": {
"type": "string",
"description": "Intake format is not evidence assessment."
},
"contract_version": {
"type": "string",
"description": "Intake disclosure version."
},
"structured_item_count": {
"type": "integer"
},
"evidence_count_semantics": {
"type": "string",
"description": "Counts submitted entries, not underlying records or verified sources."
},
"underlying_records_checked": {
"type": "boolean"
},
"content_assessment_performed": {
"type": "boolean"
},
"source_authenticity_verified": {
"type": "boolean"
},
"unstructured_description_count": {
"type": "integer"
}
}
},
"review_progress": {
"type": "object",
"properties": {
"contract_version": {
"const": "mvr.review-progress/1"
},
"scoring_eligible": {
"const": false
},
"execution_authorized": {
"const": false
},
"external_action_authorized": {
"const": false
}
},
"description": "Current case-bound review progress and residual risks. Internal evidence planning may be explicitly unreviewed; pilot designs and review packets require a separate scoped account review. No scoring, source truth or external-action permission.",
"additionalProperties": true
},
"workflow_status": {
"type": "string"
},
"decision_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"exact_next_calls": {
"type": "array",
"items": {
"type": "object"
}
},
"evidence_received": {
"type": "object"
},
"evidence_recovery": {
"type": "object",
"properties": {
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
}
}
},
"activation_outcome": {
"type": "string",
"description": "relevance_unresolved: clarify scope."
},
"next_three_unlocks": {
"type": "array",
"items": {
"type": "string"
}
},
"receipt_validation": {
"type": "object",
"properties": {
"expiry": {
"enum": [
"unknown"
],
"type": "string"
},
"status": {
"enum": [
"not_checked"
],
"type": "string"
},
"validity": {
"enum": [
"unknown"
],
"type": "string"
},
"performed": {
"enum": [
false
],
"type": "boolean"
},
"revocation": {
"enum": [
"unknown"
],
"type": "string"
}
}
},
"permission_position": {
"type": "object",
"properties": {
"tier": {
"enum": [
"prohibited",
"not_permitted",
"planning_only",
"not_applicable"
]
},
"scope": {
"const": "analysis_output"
},
"blocking_gates": {
"type": "array"
},
"contract_version": {
"const": "mvr.permission-position/1"
},
"external_effects": {
"type": "string"
},
"analysis_use_status": {
"type": "string"
},
"execution_authorized": {
"const": false
},
"narrowest_allowed_now": {
"type": "array"
},
"all_listed_gates_must_clear": {
"type": "boolean"
},
"cannot_change_the_claim_review": {
"type": [
"object",
"null"
]
}
},
"description": "Analysis-level permission position: level, what may proceed internally, every blocking gate (all must clear), decisive reviews for the claim gate (each item holding it and the act that clears it) and the evidence whose review cannot clear it. External effects are evaluated only by /v1/authority-chain check_permission. Never execution permission."
},
"workflow_expires_at": {
"type": [
"string",
"null"
]
},
"commercial_next_step": {
"type": "object"
},
"domain_routing_basis": {
"type": "string",
"description": "Routing basis, not a verified classification."
},
"evidence_field_guide": {
"type": "string",
"description": "Self-contained public evidence field types and unknown-metadata policy. Formatting guidance, not verification or authority."
},
"example_next_request": {
"type": [
"object",
"null"
]
},
"external_use_ceiling": {
"type": "object",
"required": [
"external_use_allowed",
"capability_issued"
],
"properties": {
"capability_issued": {
"const": false
},
"external_use_allowed": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
}
}
},
"mvr_response_receipt": {
"type": "object",
"required": [
"receipt_schema_version",
"mcp_tool",
"core_api_version",
"mcp_protocol_versions",
"mcp_contract_version",
"tool_profile_version",
"sdk_version",
"policy_version",
"calibration_version",
"deployment_revision",
"host_recipe_version",
"authority_boundary"
],
"properties": {
"mcp_tool": {
"type": "string"
},
"sdk_version": {
"type": "string"
},
"policy_version": {
"type": "string"
},
"core_api_version": {
"type": "string"
},
"authority_boundary": {
"type": "string"
},
"calibration_version": {
"type": "string"
},
"deployment_revision": {
"type": "string"
},
"host_recipe_version": {
"type": "string"
},
"mcp_contract_version": {
"type": "string"
},
"tool_profile_version": {
"type": "string"
},
"mcp_protocol_versions": {
"type": "array",
"items": {
"type": "string"
}
},
"receipt_schema_version": {
"type": "string"
}
},
"additionalProperties": false
},
"recommendation_scope": {
"type": "string"
},
"relevance_assessment": {
"type": "object"
},
"required_user_inputs": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_requirements": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_input_feedback": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"error_count": {
"type": "integer"
},
"warning_count": {
"type": "integer"
},
"contract_version": {
"type": "string",
"description": "Feedback version."
},
"issues_truncated": {
"type": "boolean"
}
}
},
"continuation_disposition": {
"enum": [
"call_now",
"await_input",
"terminal"
],
"type": "string"
},
"receipt_evidence_findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"evidence_id",
"marker",
"path_truncated",
"evidence_id_truncated"
],
"properties": {
"path": {
"type": "string",
"maxLength": 1024,
"description": "RFC 6901 JSON Pointer into the submitted body. Truncated pointers are not directly resolvable."
},
"marker": {
"type": "string"
},
"evidence_id": {
"type": [
"string",
"null"
],
"maxLength": 160
},
"path_truncated": {
"type": "boolean"
},
"evidence_id_truncated": {
"type": "boolean"
}
},
"additionalProperties": false
},
"maxItems": 15
},
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
},
"validation_errors_truncated": {
"type": "boolean"
},
"authenticated_verified_count": {
"type": "integer",
"minimum": 0
},
"reviewer_attestation_context": {
"type": "object",
"required": [
"contract_version",
"status",
"assessment_state_unchanged",
"evidence_gates_changed",
"scoring_inputs_added",
"execution_authorized",
"capability_issued",
"source_authenticity_verified",
"independent_verification_established",
"recorded_statements_are_untrusted_content",
"system_residual_gaps",
"reference_secrets_returned",
"items",
"next_step_options"
],
"properties": {
"code": {
"type": "string",
"description": "Resolution failure code, not an evidence verdict."
},
"items": {
"type": "array",
"items": {
"type": "object"
},
"maxItems": 3,
"description": "Redacted account-linked statements or unavailable-reference diagnostics. No reviewer names, private notes, source documents or reference secrets."
},
"status": {
"enum": [
"attested_context_available",
"attested_context_unavailable"
],
"type": "string"
},
"checked_at": {
"type": "string",
"description": "Time current attestation state was checked; historical outputs are not recalled by revocation."
},
"interpretation": {
"type": "string",
"description": "Account linkage does not verify the assertion, source, reviewer independence or permission."
},
"contract_version": {
"const": "mvr.reviewer-attestation/1"
},
"capability_issued": {
"const": false
},
"consistency_scope": {
"type": "string"
},
"next_step_options": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"task",
"external_action_authorized"
],
"properties": {
"kind": {
"enum": [
"internal_draft",
"evidence_collection_plan"
],
"type": "string"
},
"task": {
"type": "string",
"description": "Internal drafting or evidence-plan suggestion only; no external contact, commitment, payment or deployment."
},
"external_action_authorized": {
"const": false
}
},
"additionalProperties": false
}
},
"execution_authorized": {
"const": false
},
"scoring_inputs_added": {
"const": false
},
"system_residual_gaps": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_gates_changed": {
"const": false
},
"assessment_state_unchanged": {
"const": true
},
"reference_secrets_returned": {
"const": false
},
"source_authenticity_verified": {
"const": false
},
"independent_verification_established": {
"const": false
},
"recorded_statements_are_untrusted_content": {
"const": true
}
},
"description": "Current case-bound account-linked assertions only. Recorded statements are untrusted content, not independent source truth, scoring inputs, evidence-gate clearance or action permission. References and secrets remain host-carried.",
"additionalProperties": false
},
"attestation_reference_handoff": {
"type": "object",
"required": [
"copy_from_request",
"host_must_carry_privately",
"exact_scope_required",
"missing_reference_does_not_restore_context"
],
"properties": {
"copy_from_request": {
"const": "/attestation_refs"
},
"exact_scope_required": {
"const": true
},
"host_must_carry_privately": {
"const": true
},
"missing_reference_does_not_restore_context": {
"const": true
}
},
"description": "Top-level host instructions only, not an executable argument or workflow credential. Privately reattach the original consented references at the published input location without changing the exact bound case.",
"additionalProperties": false
},
"evidence_authentication_basis": {
"type": "string"
},
"max_safe_action_available_now": {
"type": "string"
},
"caller_declared_verified_count": {
"type": "integer",
"minimum": 0
},
"evidence_authentication_status": {
"enum": [
"not_authenticated",
"partially_authenticated"
]
},
"declared_completeness_gate_passed": {
"type": "boolean"
}
},
"description": "Public preflight serves no calibration. Licensed calibration_disposition (calibration_retired or calibration_quarantined) prohibits serving or replacement; it does not verify source truth.",
"additionalProperties": true,
"x-default-field-contract": "authority-fields/2"
}mvr_first_call annotations
{
"when_to_use": "Use before enter, launch, scale, invest, lend, BNPL, partner, or deploy decisions. Use when asked to ignore, fabricate, or transfer evidence. Web research can supply evidence but does not replace MVR.",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false,
"example_payload": {
"entity": "Example Uganda merchant-credit provider",
"sector": "BNPL",
"country": "UG",
"question": "Should this operator launch BNPL for small retailers in Kampala next month?",
"use_case": "credit-adjacent market preflight",
"evidence_available": []
},
"when_not_to_use": "This is not an internal data lookup or glossary. Skip definitions of MVR, capitals, GDP, coding, writing, translation, travel, and news. Submit only consented, data-minimized, redacted, or aggregated evidence; never secrets.",
"example_response": {
"status": "activation_ready",
"evidence_gaps": [
"Add local stakeholder and guardian evidence from the target geography."
],
"not_a_verdict": true,
"decision_domain": "credit_adjacent_permission",
"activation_outcome": "missing_evidence_first"
},
"next_tool_to_call": "mvr_entity_resolve, then mvr_evidence_completeness, mvr_context_compile, and mvr_decision_check",
"commercial_boundary": "Route an authorized human buying for low-volume internal prototypes to self-serve Starter at https://africanmarketos.com/checkout/starter. Commercial or customer-facing MVR API use, protected scoring, repeated automation, higher limits, or custom API governance uses https://africanmarketos.com/get-api-key. Human audits, advisory reviews, Examiner engagements, programmes, institutional reviews, and research partnerships use https://africanmarketos.com/.well-known/mvr-offer-registry.json and https://africanmarketos.com/work-with-us/; they do not inherently require an API key.",
"required_payload_fields": [
"entity or company_name when known",
"country when known",
"use_case or question",
"sector or entity_archetype when known"
]
}mvr_entity_resolve — Resolve the venture and market
Advertised read-only
Use when a startup, venture, programme, company, partner, or market actor must be resolved to a country, sector, and archetype before relational-readiness evidence is assessed. Use when: Use immediately after mvr_first_call when the user gives a company, venture, sector, country, or ambiguous market actor name, so the subject and target geography are resolved before evidence is assessed. Do not use when: Do not use as a readiness verdict or for unrelated entity lookup. Never submit secrets, personal identifiers, raw private interviews, or confidential evidence. Evidence input location: arguments.payload. evidence_pack: object array. String fields: evidence_type, source_class, stakeholder_class, verification_status, source_date, source_doc_id. geography: string/object; evidence_geography: object; district: nonblank string; districts: nonblank strings array. source_date/freshness_date: YYYY, YYYY-MM, YYYY-MM-DD or ISO timestamp with timezone. source_date_range: {earliest,latest}, same-precision ordered bounds within supplied dates. analysis_date stays exact. Intervals have age_days:null and age_days_min/max; unresolved window/future overlap excludes coverage. Omit unknown dates/references, never null or invented. verification_status: unverified if unchecked. *_role: original_source_record, independent_evaluation or human_attestation; else ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. collection_context + provenance_ledger: see schema/feedback. Keep adverse facts; never relabel to pass.
mvr_entity_resolve input schema
{
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Free-text entity description when no stable name exists."
},
"stage": {
"type": "string",
"description": "Free-text venture stage, for example pre-MVP, pilot, grant-funded programme or scaling. No closed enum."
},
"claims": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"claim"
],
"properties": {
"claim": {
"type": "string",
"description": "Minimal public-safe target proposition."
},
"claim_id": {
"type": "string",
"description": "Opaque claim identifier."
},
"support_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"evidence_id",
"relationship",
"locator"
],
"properties": {
"locator": {
"type": "string",
"description": "Specific page, cell or section. A locator is not proof."
},
"claim_id": {
"type": "string",
"description": "Must match the containing claim."
},
"evidence_id": {
"type": "string",
"description": "Must identify an item in this complete evidence pack."
},
"relationship": {
"enum": [
"direct_support",
"qualifies",
"contradicts",
"context_only"
],
"type": "string"
},
"review_event_id": {
"type": "string",
"description": "Only the licensed review service can check this event; ignored as authority by public preflight."
}
}
}
}
}
},
"description": "Optional explicit target claims and source-specific support links. Reuses the governed claim-audit vocabulary. Public links are caller declarations, never authenticated reviewer attestations."
},
"sector": {
"type": "string",
"description": "Sector or operating category when known."
},
"country": {
"type": "string",
"description": "ISO country code or country name when known."
},
"subject": {
"type": "object",
"properties": {
"entity_id": {
"type": "string"
},
"entity_name": {
"type": "string"
}
},
"description": "Exact recorded subject for attestation_refs; entity_name or entity_id required.",
"additionalProperties": true
},
"entity_name": {
"type": "string",
"description": "Venture, company, market actor, or hypothetical entity name."
},
"market_scope": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared target city."
},
"region": {
"type": "string",
"description": "Declared target region."
},
"country": {
"type": "string",
"description": "Declared target country, not the source country."
},
"corridor": {
"type": "string",
"description": "Declared target corridor."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank target district; not verified source coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Target districts as nonblank strings; empty is allowed but does not declare subnational scope."
},
"town_or_zone": {
"type": "string",
"description": "Declared target town or zone."
},
"micro_context": {
"type": "string",
"description": "Explicit local decision context."
},
"decision_scope_level": {
"enum": [
"country",
"subnational"
],
"type": "string",
"description": "Explicit decision scope. Subnational needs declared locality. A country-only decision must be declared, not inferred from absent districts."
}
},
"description": "Declared decision geography, not source geography. Supply district/districts or decision_scope_level country/subnational; subnational requires locality. A bounded Uganda target-name cross-check can require scope review, never insert districts or establish field coverage.",
"additionalProperties": true
},
"analysis_date": {
"type": "string",
"description": "Optional YYYY-MM-DD or ISO timestamp with timezone, no later than today in analysis_timezone (UTC by default). Defaults to the current date in that calendar. Carried through the public handoff."
},
"evidence_pack": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Full current evidence pack. Rechecks replace the pack; the server does not append or retrieve evidence."
},
"evidence_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Alias for evidence_pack. Supply one field, not conflicting copies."
},
"review_case_ref": {
"type": "object",
"required": [
"case_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"writeOnly": true,
"properties": {
"case_id": {
"type": "string",
"pattern": "^RC-[a-f0-9]{64}$"
},
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true
}
},
"description": "Host-private, case-bound read reference. Never put its secret into prompts, URLs, logs or exports. Grants no write or action authority.",
"additionalProperties": false
},
"attestation_refs": {
"type": "array",
"items": {
"type": "object",
"required": [
"attestation_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"properties": {
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"attestation_id": {
"type": "string",
"pattern": "^ATT-[a-f0-9]{64}$"
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true,
"description": "256-bit random bearer secret. Keep host-private, out of URLs/logs/prompts/exports; grants shared context, not authority."
}
},
"additionalProperties": false
},
"maxItems": 3,
"writeOnly": true,
"description": "Optional: https://africanmarketos.com/v1/reviewer-attestations/contract. Requires exact subject, market_scope.country and decision_question. Host-private refs outside evidence; reattach each call. No scoring or authority."
},
"entity_archetype": {
"type": "string",
"description": "Known MVR archetype, if already identified."
},
"analysis_timezone": {
"type": "string",
"description": "Optional IANA timezone, for example Africa/Nairobi, for the analysis calendar. Defaults to UTC; never inferred from country or IP. Date-only values keep their declared calendar day."
},
"decision_question": {
"type": "string",
"maxLength": 2000,
"description": "Exact recorded attestation question; question must agree when supplied."
},
"organization_type": {
"type": "string",
"description": "Founder, SME, corporate, investor, institution, or other operator type when relevant."
},
"evidence_available": {
"type": "array",
"items": {
"type": "string"
},
"description": "Short optional context labels, not proof. For supplied document summaries use incomplete evidence_pack items instead; do not mark claims verified merely because a document exists."
},
"context_freshness_window_days": {
"type": "integer",
"minimum": 1,
"description": "Optional caller-declared maximum evidence age in days. No universal freshness cutoff is invented when absent; age alone does not prove validity."
}
},
"description": "Entity and market context to canonicalize before evidence assessment.",
"minProperties": 1,
"additionalProperties": true
}
},
"additionalProperties": false
}mvr_entity_resolve output schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"status": {
"type": "string"
},
"warning": {
"type": "string"
},
"next_steps": {
"type": "object",
"required": [
"schema_version",
"purpose",
"automatic_action_authorized",
"boundary",
"offer_registry",
"options"
],
"properties": {
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"label",
"url",
"when_to_use"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"when_to_use": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 3
},
"purpose": {
"type": "string",
"const": "optional_routing_not_recommendation"
},
"boundary": {
"type": "string"
},
"offer_registry": {
"type": "string",
"format": "uri"
},
"schema_version": {
"type": "string",
"const": "mvr-optional-routing@1.0"
},
"automatic_action_authorized": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"workflow_id": {
"type": [
"string",
"null"
]
},
"claim_review": {
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object"
}
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"status": {
"type": "string"
},
"blocking": {
"type": "boolean"
},
"boundary": {
"type": "string"
},
"claim_count": {
"type": "integer"
},
"linkage_gaps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"content_item_count": {
"type": "integer"
},
"unlinked_claim_count": {
"type": "integer"
},
"linkage_gaps_truncated": {
"type": "boolean"
},
"unlinked_evidence_count": {
"type": "integer"
},
"content_assessment_performed": {
"type": "boolean"
},
"declared_contradiction_count": {
"type": "integer"
},
"declared_qualification_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"evidence_fit": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"blocking": {
"type": "boolean"
},
"analysis_date": {
"type": "string"
},
"decision_scope": {
"type": "object",
"properties": {
"level": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"declared",
"unresolved",
"not_requested"
],
"type": "string"
},
"missing_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"analysis_timezone": {
"type": [
"string",
"null"
]
},
"coverage_exclusion_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"total_errors": {
"type": "integer",
"minimum": 0
},
"mcp_next_call": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"name",
"arguments"
],
"properties": {
"name": {
"type": "string"
},
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
},
"mcp_next_tool": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"tool_name",
"arguments"
],
"properties": {
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
},
"tool_name": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"response_meta": {
"type": "object"
},
"source_review": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object"
}
},
"status": {
"type": "string"
},
"evidence_strength": {
"type": [
"number",
"null"
]
},
"required_before_consequential_reliance": {
"type": "boolean"
}
}
},
"action_boundary": {
"type": "object",
"oneOf": [
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": false
}
}
},
"decision_state": {
"enum": [
"assessment_in_progress"
]
},
"allowed_effects": {
"const": [
"read_only_assessment"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"continue_evidence_assessment"
]
},
"availability": {
"const": "exact_server_handoff"
},
"handoff_source": {
"const": "mcp_next_call"
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"versioned_internal_plan"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"evidence_collection_design",
"internal_pilot_design"
]
},
"availability": {
"const": "authenticated_case_handoff"
},
"handoff_source": {
"const": "review_progress.bounded_next_actions"
},
"required_host_inputs": {
"const": [
"current_case",
"expected_revision",
"operation_id"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"outside_declared_mvr_scope"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"ordinary_task_outside_mvr"
]
},
"availability": {
"const": "routing_only_not_permission"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"blocked_invalid_or_unavailable"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"correct_input_or_restore_current_state"
]
},
"availability": {
"const": "blocked"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"valid_input_and_current_state"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"local_internal_draft"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"internal_evidence_plan"
]
},
"availability": {
"const": "draft_only_no_external_effect"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"human_review_of_unknowns"
]
}
}
}
}
}
],
"required": [
"contract_version",
"decision_state",
"next_safe_action",
"stop",
"allowed_effects",
"forbidden_effects",
"max_capital_commitment_usd",
"external_contact_allowed",
"customer_launch_allowed",
"revalidate_before_effect",
"historical_output_is_not_current_permission",
"execution_authorized",
"external_action_authorized",
"capability_issued"
],
"properties": {
"stop": {
"type": "object",
"required": [
"required",
"applies_to",
"analytical_chain_required",
"reason_codes",
"unknown_risks_remain"
],
"properties": {
"required": {
"const": true
},
"applies_to": {
"const": "all_consequential_external_actions"
},
"reason_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"unknown_risks_remain": {
"const": true
},
"analytical_chain_required": {}
},
"additionalProperties": false
},
"decision_state": {},
"allowed_effects": {},
"contract_version": {
"const": "mvr.preflight-action-boundary/1"
},
"next_safe_action": {
"type": "object",
"required": [
"type",
"availability",
"required_host_inputs",
"handoff_source"
],
"properties": {
"type": {},
"availability": {},
"handoff_source": {},
"required_host_inputs": {}
},
"additionalProperties": false
},
"capability_issued": {
"const": false
},
"forbidden_effects": {
"const": [
"spend",
"external_contact",
"contract",
"customer_launch",
"pilot_execution",
"payment",
"deployment"
]
},
"execution_authorized": {
"const": false
},
"customer_launch_allowed": {
"const": false
},
"external_contact_allowed": {
"const": false
},
"revalidate_before_effect": {
"const": true
},
"external_action_authorized": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
},
"historical_output_is_not_current_permission": {
"const": true
}
},
"additionalProperties": false
},
"evidence_intake": {
"type": "object",
"properties": {
"status": {
"enum": [
"invalid_submission",
"described_not_structured",
"no_evidence_supplied",
"structured_items_supplied",
"mixed_descriptions_and_structured_items"
],
"type": "string"
},
"boundary": {
"type": "string",
"description": "Intake format is not evidence assessment."
},
"contract_version": {
"type": "string",
"description": "Intake disclosure version."
},
"structured_item_count": {
"type": "integer"
},
"evidence_count_semantics": {
"type": "string",
"description": "Counts submitted entries, not underlying records or verified sources."
},
"underlying_records_checked": {
"type": "boolean"
},
"content_assessment_performed": {
"type": "boolean"
},
"source_authenticity_verified": {
"type": "boolean"
},
"unstructured_description_count": {
"type": "integer"
}
}
},
"review_progress": {
"type": "object",
"properties": {
"contract_version": {
"const": "mvr.review-progress/1"
},
"scoring_eligible": {
"const": false
},
"execution_authorized": {
"const": false
},
"external_action_authorized": {
"const": false
}
},
"description": "Current case-bound review progress and residual risks. Internal evidence planning may be explicitly unreviewed; pilot designs and review packets require a separate scoped account review. No scoring, source truth or external-action permission.",
"additionalProperties": true
},
"workflow_status": {
"type": "string"
},
"canonical_entity": {
"type": [
"object",
"null"
]
},
"decision_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_recovery": {
"type": "object",
"properties": {
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
}
}
},
"receipt_validation": {
"type": "object",
"properties": {
"expiry": {
"enum": [
"unknown"
],
"type": "string"
},
"status": {
"enum": [
"not_checked"
],
"type": "string"
},
"validity": {
"enum": [
"unknown"
],
"type": "string"
},
"performed": {
"enum": [
false
],
"type": "boolean"
},
"revocation": {
"enum": [
"unknown"
],
"type": "string"
}
}
},
"permission_position": {
"type": "object",
"properties": {
"tier": {
"enum": [
"prohibited",
"not_permitted",
"planning_only",
"not_applicable"
]
},
"scope": {
"const": "analysis_output"
},
"blocking_gates": {
"type": "array"
},
"contract_version": {
"const": "mvr.permission-position/1"
},
"external_effects": {
"type": "string"
},
"analysis_use_status": {
"type": "string"
},
"execution_authorized": {
"const": false
},
"narrowest_allowed_now": {
"type": "array"
},
"all_listed_gates_must_clear": {
"type": "boolean"
},
"cannot_change_the_claim_review": {
"type": [
"object",
"null"
]
}
},
"description": "Analysis-level permission position: level, what may proceed internally, every blocking gate (all must clear), decisive reviews for the claim gate (each item holding it and the act that clears it) and the evidence whose review cannot clear it. External effects are evaluated only by /v1/authority-chain check_permission. Never execution permission."
},
"workflow_expires_at": {
"type": [
"string",
"null"
]
},
"domain_routing_basis": {
"type": "string",
"description": "Routing basis, not a verified classification."
},
"evidence_field_guide": {
"type": "string",
"description": "Self-contained public evidence field types and unknown-metadata policy. Formatting guidance, not verification or authority."
},
"external_use_ceiling": {
"type": "object",
"required": [
"external_use_allowed",
"capability_issued"
],
"properties": {
"capability_issued": {
"const": false
},
"external_use_allowed": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
}
}
},
"mvr_response_receipt": {
"type": "object",
"required": [
"receipt_schema_version",
"mcp_tool",
"core_api_version",
"mcp_protocol_versions",
"mcp_contract_version",
"tool_profile_version",
"sdk_version",
"policy_version",
"calibration_version",
"deployment_revision",
"host_recipe_version",
"authority_boundary"
],
"properties": {
"mcp_tool": {
"type": "string"
},
"sdk_version": {
"type": "string"
},
"policy_version": {
"type": "string"
},
"core_api_version": {
"type": "string"
},
"authority_boundary": {
"type": "string"
},
"calibration_version": {
"type": "string"
},
"deployment_revision": {
"type": "string"
},
"host_recipe_version": {
"type": "string"
},
"mcp_contract_version": {
"type": "string"
},
"tool_profile_version": {
"type": "string"
},
"mcp_protocol_versions": {
"type": "array",
"items": {
"type": "string"
}
},
"receipt_schema_version": {
"type": "string"
}
},
"additionalProperties": false
},
"recommendation_scope": {
"type": "string"
},
"required_user_inputs": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_requirements": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_input_feedback": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"error_count": {
"type": "integer"
},
"warning_count": {
"type": "integer"
},
"contract_version": {
"type": "string",
"description": "Feedback version."
},
"issues_truncated": {
"type": "boolean"
}
}
},
"continuation_disposition": {
"enum": [
"call_now",
"await_input",
"terminal"
],
"type": "string"
},
"receipt_evidence_findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"evidence_id",
"marker",
"path_truncated",
"evidence_id_truncated"
],
"properties": {
"path": {
"type": "string",
"maxLength": 1024,
"description": "RFC 6901 JSON Pointer into the submitted body. Truncated pointers are not directly resolvable."
},
"marker": {
"type": "string"
},
"evidence_id": {
"type": [
"string",
"null"
],
"maxLength": 160
},
"path_truncated": {
"type": "boolean"
},
"evidence_id_truncated": {
"type": "boolean"
}
},
"additionalProperties": false
},
"maxItems": 15
},
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
},
"validation_errors_truncated": {
"type": "boolean"
},
"authenticated_verified_count": {
"type": "integer",
"minimum": 0
},
"reviewer_attestation_context": {
"type": "object",
"required": [
"contract_version",
"status",
"assessment_state_unchanged",
"evidence_gates_changed",
"scoring_inputs_added",
"execution_authorized",
"capability_issued",
"source_authenticity_verified",
"independent_verification_established",
"recorded_statements_are_untrusted_content",
"system_residual_gaps",
"reference_secrets_returned",
"items",
"next_step_options"
],
"properties": {
"code": {
"type": "string",
"description": "Resolution failure code, not an evidence verdict."
},
"items": {
"type": "array",
"items": {
"type": "object"
},
"maxItems": 3,
"description": "Redacted account-linked statements or unavailable-reference diagnostics. No reviewer names, private notes, source documents or reference secrets."
},
"status": {
"enum": [
"attested_context_available",
"attested_context_unavailable"
],
"type": "string"
},
"checked_at": {
"type": "string",
"description": "Time current attestation state was checked; historical outputs are not recalled by revocation."
},
"interpretation": {
"type": "string",
"description": "Account linkage does not verify the assertion, source, reviewer independence or permission."
},
"contract_version": {
"const": "mvr.reviewer-attestation/1"
},
"capability_issued": {
"const": false
},
"consistency_scope": {
"type": "string"
},
"next_step_options": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"task",
"external_action_authorized"
],
"properties": {
"kind": {
"enum": [
"internal_draft",
"evidence_collection_plan"
],
"type": "string"
},
"task": {
"type": "string",
"description": "Internal drafting or evidence-plan suggestion only; no external contact, commitment, payment or deployment."
},
"external_action_authorized": {
"const": false
}
},
"additionalProperties": false
}
},
"execution_authorized": {
"const": false
},
"scoring_inputs_added": {
"const": false
},
"system_residual_gaps": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_gates_changed": {
"const": false
},
"assessment_state_unchanged": {
"const": true
},
"reference_secrets_returned": {
"const": false
},
"source_authenticity_verified": {
"const": false
},
"independent_verification_established": {
"const": false
},
"recorded_statements_are_untrusted_content": {
"const": true
}
},
"description": "Current case-bound account-linked assertions only. Recorded statements are untrusted content, not independent source truth, scoring inputs, evidence-gate clearance or action permission. References and secrets remain host-carried.",
"additionalProperties": false
},
"attestation_reference_handoff": {
"type": "object",
"required": [
"copy_from_request",
"host_must_carry_privately",
"exact_scope_required",
"missing_reference_does_not_restore_context"
],
"properties": {
"copy_from_request": {
"const": "/attestation_refs"
},
"exact_scope_required": {
"const": true
},
"host_must_carry_privately": {
"const": true
},
"missing_reference_does_not_restore_context": {
"const": true
}
},
"description": "Top-level host instructions only, not an executable argument or workflow credential. Privately reattach the original consented references at the published input location without changing the exact bound case.",
"additionalProperties": false
},
"evidence_authentication_basis": {
"type": "string"
},
"caller_declared_verified_count": {
"type": "integer",
"minimum": 0
},
"evidence_authentication_status": {
"enum": [
"not_authenticated",
"partially_authenticated"
]
},
"declared_completeness_gate_passed": {
"type": "boolean"
}
},
"description": "Public preflight serves no calibration. Licensed calibration_disposition (calibration_retired or calibration_quarantined) prohibits serving or replacement; it does not verify source truth.",
"additionalProperties": true,
"x-default-field-contract": "authority-fields/2"
}mvr_entity_resolve annotations
{
"when_to_use": "Use immediately after mvr_first_call when the user gives a company, venture, sector, country, or ambiguous market actor name, so the subject and target geography are resolved before evidence is assessed.",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false,
"example_payload": {
"sector": "fintech",
"country": "UG",
"entity_name": "Example Uganda merchant-credit fintech"
},
"when_not_to_use": "Do not use as a readiness verdict or for unrelated entity lookup. Never submit secrets, personal identifiers, raw private interviews, or confidential evidence.",
"example_response": {
"status": "resolved",
"canonical_entity": {
"name": "Example Uganda merchant-credit fintech",
"country": "UG",
"confidence": "sandbox_inferred",
"entity_archetype": "fintech"
}
},
"next_tool_to_call": "mvr_evidence_completeness",
"commercial_boundary": "Sandbox is illustrative and non-commercial. Production entity resolution requires a licensed MVR API key.",
"required_payload_fields": [
"entity_name or query",
"country or market_scope.country when known",
"sector or entity_archetype when known"
]
}mvr_evidence_completeness — Check evidence completeness
Advertised read-only
Use after entity resolution and before any readiness claim to check verification status, source-family diversity, stakeholder coverage, and missing proof. Do not treat completeness as authorization. Use when: Use after entity resolution and before any verdict when evidence may be incomplete or one-sided. Do not use when: Do not treat completeness as readiness or authorization. Submit only consented, data-minimized, redacted or aggregated evidence; never raw private interviews, secrets, credentials, or personal identifiers. Evidence input location: arguments.payload. evidence_pack: object array. String fields: evidence_type, source_class, stakeholder_class, verification_status, source_date, source_doc_id. geography: string/object; evidence_geography: object; district: nonblank string; districts: nonblank strings array. source_date/freshness_date: YYYY, YYYY-MM, YYYY-MM-DD or ISO timestamp with timezone. source_date_range: {earliest,latest}, same-precision ordered bounds within supplied dates. analysis_date stays exact. Intervals have age_days:null and age_days_min/max; unresolved window/future overlap excludes coverage. Omit unknown dates/references, never null or invented. verification_status: unverified if unchecked. *_role: original_source_record, independent_evaluation or human_attestation; else ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. collection_context + provenance_ledger: see schema/feedback. Keep adverse facts; never relabel to pass.
mvr_evidence_completeness input schema
{
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"description": "Free-text venture stage, for example pre-MVP, pilot, grant-funded programme or scaling. No closed enum."
},
"claims": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"claim"
],
"properties": {
"claim": {
"type": "string",
"description": "Minimal public-safe target proposition."
},
"claim_id": {
"type": "string",
"description": "Opaque claim identifier."
},
"support_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"evidence_id",
"relationship",
"locator"
],
"properties": {
"locator": {
"type": "string",
"description": "Specific page, cell or section. A locator is not proof."
},
"claim_id": {
"type": "string",
"description": "Must match the containing claim."
},
"evidence_id": {
"type": "string",
"description": "Must identify an item in this complete evidence pack."
},
"relationship": {
"enum": [
"direct_support",
"qualifies",
"contradicts",
"context_only"
],
"type": "string"
},
"review_event_id": {
"type": "string",
"description": "Only the licensed review service can check this event; ignored as authority by public preflight."
}
}
}
}
}
},
"description": "Optional explicit target claims and source-specific support links. Reuses the governed claim-audit vocabulary. Public links are caller declarations, never authenticated reviewer attestations."
},
"subject": {
"type": "object",
"properties": {
"sector": {
"type": "string"
},
"entity_id": {
"type": "string"
},
"entity_name": {
"type": "string"
},
"entity_archetype": {
"type": "string"
}
},
"description": "Resolved or supplied entity under assessment.",
"additionalProperties": true
},
"market_scope": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared target city."
},
"region": {
"type": "string",
"description": "Declared target region."
},
"country": {
"type": "string",
"description": "Declared target country, not the source country."
},
"corridor": {
"type": "string",
"description": "Declared target corridor."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank target district; not verified source coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Target districts as nonblank strings; empty is allowed but does not declare subnational scope."
},
"town_or_zone": {
"type": "string",
"description": "Declared target town or zone."
},
"micro_context": {
"type": "string",
"description": "Explicit local decision context."
},
"decision_scope_level": {
"enum": [
"country",
"subnational"
],
"type": "string",
"description": "Explicit decision scope. Subnational needs declared locality. A country-only decision must be declared, not inferred from absent districts."
}
},
"description": "Declared decision geography, not source geography. Supply district/districts or decision_scope_level country/subnational; subnational requires locality. A bounded Uganda target-name cross-check can require scope review, never insert districts or establish field coverage.",
"additionalProperties": true
},
"target_claim": {
"type": "string",
"description": "Claim or readiness question the evidence is meant to support."
},
"analysis_date": {
"type": "string",
"description": "Optional YYYY-MM-DD or ISO timestamp with timezone, no later than today in analysis_timezone (UTC by default). Defaults to the current date in that calendar. Carried through the public handoff."
},
"evidence_pack": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Full current evidence pack. Rechecks replace the pack; the server does not append or retrieve evidence."
},
"decision_stage": {
"type": "string",
"description": "Idea, pre-entry, pilot, launch, expansion, or scale stage."
},
"evidence_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Alias for evidence_pack. Supply one field, not conflicting copies."
},
"review_case_ref": {
"type": "object",
"required": [
"case_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"writeOnly": true,
"properties": {
"case_id": {
"type": "string",
"pattern": "^RC-[a-f0-9]{64}$"
},
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true
}
},
"description": "Host-private, case-bound read reference. Never put its secret into prompts, URLs, logs or exports. Grants no write or action authority.",
"additionalProperties": false
},
"attestation_refs": {
"type": "array",
"items": {
"type": "object",
"required": [
"attestation_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"properties": {
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"attestation_id": {
"type": "string",
"pattern": "^ATT-[a-f0-9]{64}$"
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true,
"description": "256-bit random bearer secret. Keep host-private, out of URLs/logs/prompts/exports; grants shared context, not authority."
}
},
"additionalProperties": false
},
"maxItems": 3,
"writeOnly": true,
"description": "Optional: https://africanmarketos.com/v1/reviewer-attestations/contract. Requires exact subject, market_scope.country and decision_question. Host-private refs outside evidence; reattach each call. No scoring or authority."
},
"analysis_timezone": {
"type": "string",
"description": "Optional IANA timezone, for example Africa/Nairobi, for the analysis calendar. Defaults to UTC; never inferred from country or IP. Date-only values keep their declared calendar day."
},
"decision_question": {
"type": "string",
"maxLength": 2000,
"description": "Exact recorded attestation question; question must agree when supplied."
},
"evidence_available": {
"type": "array",
"items": {
"type": "string"
},
"description": "Short optional context labels, not proof. For supplied document summaries use incomplete evidence_pack items instead; do not mark claims verified merely because a document exists."
},
"context_freshness_window_days": {
"type": "integer",
"minimum": 1,
"description": "Optional caller-declared maximum evidence age in days. No universal freshness cutoff is invented when absent; age alone does not prove validity."
}
},
"description": "Evidence pack and decision context to test for missing proof.",
"additionalProperties": true
}
},
"additionalProperties": false
}mvr_evidence_completeness output schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"status": {
"type": "string"
},
"next_steps": {
"type": "object",
"required": [
"schema_version",
"purpose",
"automatic_action_authorized",
"boundary",
"offer_registry",
"options"
],
"properties": {
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"label",
"url",
"when_to_use"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"when_to_use": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 3
},
"purpose": {
"type": "string",
"const": "optional_routing_not_recommendation"
},
"boundary": {
"type": "string"
},
"offer_registry": {
"type": "string",
"format": "uri"
},
"schema_version": {
"type": "string",
"const": "mvr-optional-routing@1.0"
},
"automatic_action_authorized": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"workflow_id": {
"type": [
"string",
"null"
]
},
"claim_review": {
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object"
}
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"status": {
"type": "string"
},
"blocking": {
"type": "boolean"
},
"boundary": {
"type": "string"
},
"claim_count": {
"type": "integer"
},
"linkage_gaps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"content_item_count": {
"type": "integer"
},
"unlinked_claim_count": {
"type": "integer"
},
"linkage_gaps_truncated": {
"type": "boolean"
},
"unlinked_evidence_count": {
"type": "integer"
},
"content_assessment_performed": {
"type": "boolean"
},
"declared_contradiction_count": {
"type": "integer"
},
"declared_qualification_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"evidence_fit": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"blocking": {
"type": "boolean"
},
"analysis_date": {
"type": "string"
},
"decision_scope": {
"type": "object",
"properties": {
"level": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"declared",
"unresolved",
"not_requested"
],
"type": "string"
},
"missing_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"analysis_timezone": {
"type": [
"string",
"null"
]
},
"coverage_exclusion_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"total_errors": {
"type": "integer",
"minimum": 0
},
"evidence_gaps": {
"type": "array",
"items": {
"type": "string"
}
},
"mcp_next_call": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"name",
"arguments"
],
"properties": {
"name": {
"type": "string"
},
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
},
"mcp_next_tool": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"tool_name",
"arguments"
],
"properties": {
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
},
"tool_name": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"response_meta": {
"type": "object"
},
"source_review": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object"
}
},
"status": {
"type": "string"
},
"evidence_strength": {
"type": [
"number",
"null"
]
},
"required_before_consequential_reliance": {
"type": "boolean"
}
}
},
"evidence_count": {
"type": "number"
},
"action_boundary": {
"type": "object",
"oneOf": [
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": false
}
}
},
"decision_state": {
"enum": [
"assessment_in_progress"
]
},
"allowed_effects": {
"const": [
"read_only_assessment"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"continue_evidence_assessment"
]
},
"availability": {
"const": "exact_server_handoff"
},
"handoff_source": {
"const": "mcp_next_call"
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"versioned_internal_plan"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"evidence_collection_design",
"internal_pilot_design"
]
},
"availability": {
"const": "authenticated_case_handoff"
},
"handoff_source": {
"const": "review_progress.bounded_next_actions"
},
"required_host_inputs": {
"const": [
"current_case",
"expected_revision",
"operation_id"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"outside_declared_mvr_scope"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"ordinary_task_outside_mvr"
]
},
"availability": {
"const": "routing_only_not_permission"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"blocked_invalid_or_unavailable"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"correct_input_or_restore_current_state"
]
},
"availability": {
"const": "blocked"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"valid_input_and_current_state"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"local_internal_draft"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"internal_evidence_plan"
]
},
"availability": {
"const": "draft_only_no_external_effect"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"human_review_of_unknowns"
]
}
}
}
}
}
],
"required": [
"contract_version",
"decision_state",
"next_safe_action",
"stop",
"allowed_effects",
"forbidden_effects",
"max_capital_commitment_usd",
"external_contact_allowed",
"customer_launch_allowed",
"revalidate_before_effect",
"historical_output_is_not_current_permission",
"execution_authorized",
"external_action_authorized",
"capability_issued"
],
"properties": {
"stop": {
"type": "object",
"required": [
"required",
"applies_to",
"analytical_chain_required",
"reason_codes",
"unknown_risks_remain"
],
"properties": {
"required": {
"const": true
},
"applies_to": {
"const": "all_consequential_external_actions"
},
"reason_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"unknown_risks_remain": {
"const": true
},
"analytical_chain_required": {}
},
"additionalProperties": false
},
"decision_state": {},
"allowed_effects": {},
"contract_version": {
"const": "mvr.preflight-action-boundary/1"
},
"next_safe_action": {
"type": "object",
"required": [
"type",
"availability",
"required_host_inputs",
"handoff_source"
],
"properties": {
"type": {},
"availability": {},
"handoff_source": {},
"required_host_inputs": {}
},
"additionalProperties": false
},
"capability_issued": {
"const": false
},
"forbidden_effects": {
"const": [
"spend",
"external_contact",
"contract",
"customer_launch",
"pilot_execution",
"payment",
"deployment"
]
},
"execution_authorized": {
"const": false
},
"customer_launch_allowed": {
"const": false
},
"external_contact_allowed": {
"const": false
},
"revalidate_before_effect": {
"const": true
},
"external_action_authorized": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
},
"historical_output_is_not_current_permission": {
"const": true
}
},
"additionalProperties": false
},
"evidence_intake": {
"type": "object",
"properties": {
"status": {
"enum": [
"invalid_submission",
"described_not_structured",
"no_evidence_supplied",
"structured_items_supplied",
"mixed_descriptions_and_structured_items"
],
"type": "string"
},
"boundary": {
"type": "string",
"description": "Intake format is not evidence assessment."
},
"contract_version": {
"type": "string",
"description": "Intake disclosure version."
},
"structured_item_count": {
"type": "integer"
},
"evidence_count_semantics": {
"type": "string",
"description": "Counts submitted entries, not underlying records or verified sources."
},
"underlying_records_checked": {
"type": "boolean"
},
"content_assessment_performed": {
"type": "boolean"
},
"source_authenticity_verified": {
"type": "boolean"
},
"unstructured_description_count": {
"type": "integer"
}
}
},
"review_progress": {
"type": "object",
"properties": {
"contract_version": {
"const": "mvr.review-progress/1"
},
"scoring_eligible": {
"const": false
},
"execution_authorized": {
"const": false
},
"external_action_authorized": {
"const": false
}
},
"description": "Current case-bound review progress and residual risks. Internal evidence planning may be explicitly unreviewed; pilot designs and review packets require a separate scoped account review. No scoring, source truth or external-action permission.",
"additionalProperties": true
},
"workflow_status": {
"type": "string"
},
"decision_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"safe_next_action": {
"type": "string"
},
"evidence_recovery": {
"type": "object",
"properties": {
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
}
}
},
"receipt_validation": {
"type": "object",
"properties": {
"expiry": {
"enum": [
"unknown"
],
"type": "string"
},
"status": {
"enum": [
"not_checked"
],
"type": "string"
},
"validity": {
"enum": [
"unknown"
],
"type": "string"
},
"performed": {
"enum": [
false
],
"type": "boolean"
},
"revocation": {
"enum": [
"unknown"
],
"type": "string"
}
}
},
"verification_basis": {
"type": "string"
},
"permission_position": {
"type": "object",
"properties": {
"tier": {
"enum": [
"prohibited",
"not_permitted",
"planning_only",
"not_applicable"
]
},
"scope": {
"const": "analysis_output"
},
"blocking_gates": {
"type": "array"
},
"contract_version": {
"const": "mvr.permission-position/1"
},
"external_effects": {
"type": "string"
},
"analysis_use_status": {
"type": "string"
},
"execution_authorized": {
"const": false
},
"narrowest_allowed_now": {
"type": "array"
},
"all_listed_gates_must_clear": {
"type": "boolean"
},
"cannot_change_the_claim_review": {
"type": [
"object",
"null"
]
}
},
"description": "Analysis-level permission position: level, what may proceed internally, every blocking gate (all must clear), decisive reviews for the claim gate (each item holding it and the act that clears it) and the evidence whose review cannot clear it. External effects are evaluated only by /v1/authority-chain check_permission. Never execution permission."
},
"workflow_expires_at": {
"type": [
"string",
"null"
]
},
"domain_routing_basis": {
"type": "string",
"description": "Routing basis, not a verified classification."
},
"evidence_field_guide": {
"type": "string",
"description": "Self-contained public evidence field types and unknown-metadata policy. Formatting guidance, not verification or authority."
},
"external_use_ceiling": {
"type": "object",
"required": [
"external_use_allowed",
"capability_issued"
],
"properties": {
"capability_issued": {
"const": false
},
"external_use_allowed": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
}
}
},
"mvr_response_receipt": {
"type": "object",
"required": [
"receipt_schema_version",
"mcp_tool",
"core_api_version",
"mcp_protocol_versions",
"mcp_contract_version",
"tool_profile_version",
"sdk_version",
"policy_version",
"calibration_version",
"deployment_revision",
"host_recipe_version",
"authority_boundary"
],
"properties": {
"mcp_tool": {
"type": "string"
},
"sdk_version": {
"type": "string"
},
"policy_version": {
"type": "string"
},
"core_api_version": {
"type": "string"
},
"authority_boundary": {
"type": "string"
},
"calibration_version": {
"type": "string"
},
"deployment_revision": {
"type": "string"
},
"host_recipe_version": {
"type": "string"
},
"mcp_contract_version": {
"type": "string"
},
"tool_profile_version": {
"type": "string"
},
"mcp_protocol_versions": {
"type": "array",
"items": {
"type": "string"
}
},
"receipt_schema_version": {
"type": "string"
}
},
"additionalProperties": false
},
"recommendation_scope": {
"type": "string"
},
"required_user_inputs": {
"type": "array",
"items": {
"type": "string"
}
},
"stakeholder_coverage": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_requirements": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_input_feedback": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"error_count": {
"type": "integer"
},
"warning_count": {
"type": "integer"
},
"contract_version": {
"type": "string",
"description": "Feedback version."
},
"issues_truncated": {
"type": "boolean"
}
}
},
"continuation_disposition": {
"enum": [
"call_now",
"await_input",
"terminal"
],
"type": "string"
},
"verified_source_families": {
"type": "array",
"items": {
"type": "string"
}
},
"receipt_evidence_findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"evidence_id",
"marker",
"path_truncated",
"evidence_id_truncated"
],
"properties": {
"path": {
"type": "string",
"maxLength": 1024,
"description": "RFC 6901 JSON Pointer into the submitted body. Truncated pointers are not directly resolvable."
},
"marker": {
"type": "string"
},
"evidence_id": {
"type": [
"string",
"null"
],
"maxLength": 160
},
"path_truncated": {
"type": "boolean"
},
"evidence_id_truncated": {
"type": "boolean"
}
},
"additionalProperties": false
},
"maxItems": 15
},
"unverified_evidence_count": {
"type": "number"
},
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
},
"validation_errors_truncated": {
"type": "boolean"
},
"authenticated_verified_count": {
"type": "integer",
"minimum": 0
},
"reviewer_attestation_context": {
"type": "object",
"required": [
"contract_version",
"status",
"assessment_state_unchanged",
"evidence_gates_changed",
"scoring_inputs_added",
"execution_authorized",
"capability_issued",
"source_authenticity_verified",
"independent_verification_established",
"recorded_statements_are_untrusted_content",
"system_residual_gaps",
"reference_secrets_returned",
"items",
"next_step_options"
],
"properties": {
"code": {
"type": "string",
"description": "Resolution failure code, not an evidence verdict."
},
"items": {
"type": "array",
"items": {
"type": "object"
},
"maxItems": 3,
"description": "Redacted account-linked statements or unavailable-reference diagnostics. No reviewer names, private notes, source documents or reference secrets."
},
"status": {
"enum": [
"attested_context_available",
"attested_context_unavailable"
],
"type": "string"
},
"checked_at": {
"type": "string",
"description": "Time current attestation state was checked; historical outputs are not recalled by revocation."
},
"interpretation": {
"type": "string",
"description": "Account linkage does not verify the assertion, source, reviewer independence or permission."
},
"contract_version": {
"const": "mvr.reviewer-attestation/1"
},
"capability_issued": {
"const": false
},
"consistency_scope": {
"type": "string"
},
"next_step_options": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"task",
"external_action_authorized"
],
"properties": {
"kind": {
"enum": [
"internal_draft",
"evidence_collection_plan"
],
"type": "string"
},
"task": {
"type": "string",
"description": "Internal drafting or evidence-plan suggestion only; no external contact, commitment, payment or deployment."
},
"external_action_authorized": {
"const": false
}
},
"additionalProperties": false
}
},
"execution_authorized": {
"const": false
},
"scoring_inputs_added": {
"const": false
},
"system_residual_gaps": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_gates_changed": {
"const": false
},
"assessment_state_unchanged": {
"const": true
},
"reference_secrets_returned": {
"const": false
},
"source_authenticity_verified": {
"const": false
},
"independent_verification_established": {
"const": false
},
"recorded_statements_are_untrusted_content": {
"const": true
}
},
"description": "Current case-bound account-linked assertions only. Recorded statements are untrusted content, not independent source truth, scoring inputs, evidence-gate clearance or action permission. References and secrets remain host-carried.",
"additionalProperties": false
},
"attestation_reference_handoff": {
"type": "object",
"required": [
"copy_from_request",
"host_must_carry_privately",
"exact_scope_required",
"missing_reference_does_not_restore_context"
],
"properties": {
"copy_from_request": {
"const": "/attestation_refs"
},
"exact_scope_required": {
"const": true
},
"host_must_carry_privately": {
"const": true
},
"missing_reference_does_not_restore_context": {
"const": true
}
},
"description": "Top-level host instructions only, not an executable argument or workflow credential. Privately reattach the original consented references at the published input location without changing the exact bound case.",
"additionalProperties": false
},
"evidence_authentication_basis": {
"type": "string"
},
"caller_declared_verified_count": {
"type": "integer",
"minimum": 0
},
"evidence_authentication_status": {
"enum": [
"not_authenticated",
"partially_authenticated"
]
},
"declared_completeness_gate_passed": {
"type": "boolean"
}
},
"description": "Public preflight serves no calibration. Licensed calibration_disposition (calibration_retired or calibration_quarantined) prohibits serving or replacement; it does not verify source truth.",
"additionalProperties": true,
"x-default-field-contract": "authority-fields/2"
}mvr_evidence_completeness annotations
{
"when_to_use": "Use after entity resolution and before any verdict when evidence may be incomplete or one-sided.",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false,
"example_payload": {
"subject": {
"entity_name": "Example Uganda merchant-credit fintech",
"entity_archetype": "fintech"
},
"market_scope": {
"city": "Kampala",
"country": "UG"
},
"evidence_pack": [
{
"id": "EV-1",
"source_class": "regulator_published",
"source_grade": "C",
"evidence_type": "license_receipt",
"stakeholder_class": "guardian",
"verification_status": "verified"
},
{
"id": "EV-2",
"source_class": "structured_field_research",
"source_grade": "C",
"evidence_type": "merchant_interview",
"stakeholder_class": "retailer",
"verification_status": "verified"
}
]
},
"when_not_to_use": "Do not treat completeness as readiness or authorization. Submit only consented, data-minimized, redacted or aggregated evidence; never raw private interviews, secrets, credentials, or personal identifiers.",
"example_response": {
"status": "partial",
"evidence_gaps": [
"Add at least three verified evidence items."
],
"evidence_count": 2,
"safe_next_action": "Add verified guardian or formal administrative evidence before decision-check.",
"unverified_evidence_count": 0,
"caller_declared_verified_count": 2
},
"next_tool_to_call": "mvr_context_compile, then mvr_decision_check when gaps are closed",
"commercial_boundary": "Sandbox completeness checks are advisory only. Production diligence, investor, accelerator, NGO, DFI, or customer-facing use requires licensed access.",
"required_payload_fields": [
"evidence_pack or evidence_items array",
"verification_status on every evidence item",
"source_class or evidence_origin on every evidence item",
"source_url or explicit provenance_ledger.source_doc_id/source_locator; repeated references count together, not as independent evidence",
"stakeholder_class on evidence where possible",
"market_scope for geographic context"
]
}mvr_context_compile — Compile evidence context
Advertised read-only
Use after evidence capture to separate safe from unsafe inferences across formal, field, market, trust, and stakeholder context. It compiles context; it does not authorize action. Use when: Use when evidence is mixed and the agent needs safe claims versus unsafe claims before a verdict. Do not use when: Do not use as a go/no-go decision. Submit only consented, data-minimized, redacted or aggregated evidence; never raw confidential datasets, secrets, credentials, or personal identifiers. Evidence input location: arguments.payload. evidence_pack: object array. String fields: evidence_type, source_class, stakeholder_class, verification_status, source_date, source_doc_id. geography: string/object; evidence_geography: object; district: nonblank string; districts: nonblank strings array. source_date/freshness_date: YYYY, YYYY-MM, YYYY-MM-DD or ISO timestamp with timezone. source_date_range: {earliest,latest}, same-precision ordered bounds within supplied dates. analysis_date stays exact. Intervals have age_days:null and age_days_min/max; unresolved window/future overlap excludes coverage. Omit unknown dates/references, never null or invented. verification_status: unverified if unchecked. *_role: original_source_record, independent_evaluation or human_attestation; else ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. collection_context + provenance_ledger: see schema/feedback. Keep adverse facts; never relabel to pass.
mvr_context_compile input schema
{
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"description": "Free-text venture stage, for example pre-MVP, pilot, grant-funded programme or scaling. No closed enum."
},
"claims": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"claim"
],
"properties": {
"claim": {
"type": "string",
"description": "Minimal public-safe target proposition."
},
"claim_id": {
"type": "string",
"description": "Opaque claim identifier."
},
"support_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"evidence_id",
"relationship",
"locator"
],
"properties": {
"locator": {
"type": "string",
"description": "Specific page, cell or section. A locator is not proof."
},
"claim_id": {
"type": "string",
"description": "Must match the containing claim."
},
"evidence_id": {
"type": "string",
"description": "Must identify an item in this complete evidence pack."
},
"relationship": {
"enum": [
"direct_support",
"qualifies",
"contradicts",
"context_only"
],
"type": "string"
},
"review_event_id": {
"type": "string",
"description": "Only the licensed review service can check this event; ignored as authority by public preflight."
}
}
}
}
}
},
"description": "Optional explicit target claims and source-specific support links. Reuses the governed claim-audit vocabulary. Public links are caller declarations, never authenticated reviewer attestations."
},
"subject": {
"type": "object",
"properties": {
"sector": {
"type": "string"
},
"entity_id": {
"type": "string"
},
"entity_name": {
"type": "string"
},
"entity_archetype": {
"type": "string"
}
},
"description": "Resolved or supplied entity under assessment.",
"additionalProperties": true
},
"market_scope": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared target city."
},
"region": {
"type": "string",
"description": "Declared target region."
},
"country": {
"type": "string",
"description": "Declared target country, not the source country."
},
"corridor": {
"type": "string",
"description": "Declared target corridor."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank target district; not verified source coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Target districts as nonblank strings; empty is allowed but does not declare subnational scope."
},
"town_or_zone": {
"type": "string",
"description": "Declared target town or zone."
},
"micro_context": {
"type": "string",
"description": "Explicit local decision context."
},
"decision_scope_level": {
"enum": [
"country",
"subnational"
],
"type": "string",
"description": "Explicit decision scope. Subnational needs declared locality. A country-only decision must be declared, not inferred from absent districts."
}
},
"description": "Declared decision geography, not source geography. Supply district/districts or decision_scope_level country/subnational; subnational requires locality. A bounded Uganda target-name cross-check can require scope review, never insert districts or establish field coverage.",
"additionalProperties": true
},
"target_claim": {
"type": "string"
},
"analysis_date": {
"type": "string",
"description": "Optional YYYY-MM-DD or ISO timestamp with timezone, no later than today in analysis_timezone (UTC by default). Defaults to the current date in that calendar. Carried through the public handoff."
},
"evidence_pack": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Full current evidence pack. Rechecks replace the pack; the server does not append or retrieve evidence."
},
"decision_stage": {
"type": "string"
},
"evidence_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Alias for evidence_pack. Supply one field, not conflicting copies."
},
"review_case_ref": {
"type": "object",
"required": [
"case_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"writeOnly": true,
"properties": {
"case_id": {
"type": "string",
"pattern": "^RC-[a-f0-9]{64}$"
},
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true
}
},
"description": "Host-private, case-bound read reference. Never put its secret into prompts, URLs, logs or exports. Grants no write or action authority.",
"additionalProperties": false
},
"attestation_refs": {
"type": "array",
"items": {
"type": "object",
"required": [
"attestation_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"properties": {
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"attestation_id": {
"type": "string",
"pattern": "^ATT-[a-f0-9]{64}$"
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true,
"description": "256-bit random bearer secret. Keep host-private, out of URLs/logs/prompts/exports; grants shared context, not authority."
}
},
"additionalProperties": false
},
"maxItems": 3,
"writeOnly": true,
"description": "Optional: https://africanmarketos.com/v1/reviewer-attestations/contract. Requires exact subject, market_scope.country and decision_question. Host-private refs outside evidence; reattach each call. No scoring or authority."
},
"analysis_timezone": {
"type": "string",
"description": "Optional IANA timezone, for example Africa/Nairobi, for the analysis calendar. Defaults to UTC; never inferred from country or IP. Date-only values keep their declared calendar day."
},
"decision_question": {
"type": "string",
"maxLength": 2000,
"description": "Exact recorded attestation question; question must agree when supplied."
},
"evidence_available": {
"type": "array",
"items": {
"type": "string"
},
"description": "Short optional context labels, not proof. For supplied document summaries use incomplete evidence_pack items instead; do not mark claims verified merely because a document exists."
},
"context_freshness_window_days": {
"type": "integer",
"minimum": 1,
"description": "Optional caller-declared maximum evidence age in days. No universal freshness cutoff is invented when absent; age alone does not prove validity."
}
},
"description": "Resolved subject, market scope, and mixed evidence to compile into safe and unsafe inferences.",
"additionalProperties": true
}
},
"additionalProperties": false
}mvr_context_compile output schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"status": {
"type": "string"
},
"next_steps": {
"type": "object",
"required": [
"schema_version",
"purpose",
"automatic_action_authorized",
"boundary",
"offer_registry",
"options"
],
"properties": {
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"label",
"url",
"when_to_use"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"when_to_use": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 3
},
"purpose": {
"type": "string",
"const": "optional_routing_not_recommendation"
},
"boundary": {
"type": "string"
},
"offer_registry": {
"type": "string",
"format": "uri"
},
"schema_version": {
"type": "string",
"const": "mvr-optional-routing@1.0"
},
"automatic_action_authorized": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"workflow_id": {
"type": [
"string",
"null"
]
},
"claim_review": {
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object"
}
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"status": {
"type": "string"
},
"blocking": {
"type": "boolean"
},
"boundary": {
"type": "string"
},
"claim_count": {
"type": "integer"
},
"linkage_gaps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"content_item_count": {
"type": "integer"
},
"unlinked_claim_count": {
"type": "integer"
},
"linkage_gaps_truncated": {
"type": "boolean"
},
"unlinked_evidence_count": {
"type": "integer"
},
"content_assessment_performed": {
"type": "boolean"
},
"declared_contradiction_count": {
"type": "integer"
},
"declared_qualification_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"evidence_fit": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"blocking": {
"type": "boolean"
},
"analysis_date": {
"type": "string"
},
"decision_scope": {
"type": "object",
"properties": {
"level": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"declared",
"unresolved",
"not_requested"
],
"type": "string"
},
"missing_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"analysis_timezone": {
"type": [
"string",
"null"
]
},
"coverage_exclusion_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"formal_proof": {
"type": "number"
},
"total_errors": {
"type": "integer",
"minimum": 0
},
"mcp_next_call": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"name",
"arguments"
],
"properties": {
"name": {
"type": "string"
},
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
},
"mcp_next_tool": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"tool_name",
"arguments"
],
"properties": {
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
},
"tool_name": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"response_meta": {
"type": "object"
},
"source_review": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object"
}
},
"status": {
"type": "string"
},
"evidence_strength": {
"type": [
"number",
"null"
]
},
"required_before_consequential_reliance": {
"type": "boolean"
}
}
},
"action_boundary": {
"type": "object",
"oneOf": [
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": false
}
}
},
"decision_state": {
"enum": [
"assessment_in_progress"
]
},
"allowed_effects": {
"const": [
"read_only_assessment"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"continue_evidence_assessment"
]
},
"availability": {
"const": "exact_server_handoff"
},
"handoff_source": {
"const": "mcp_next_call"
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"versioned_internal_plan"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"evidence_collection_design",
"internal_pilot_design"
]
},
"availability": {
"const": "authenticated_case_handoff"
},
"handoff_source": {
"const": "review_progress.bounded_next_actions"
},
"required_host_inputs": {
"const": [
"current_case",
"expected_revision",
"operation_id"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"outside_declared_mvr_scope"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"ordinary_task_outside_mvr"
]
},
"availability": {
"const": "routing_only_not_permission"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"blocked_invalid_or_unavailable"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"correct_input_or_restore_current_state"
]
},
"availability": {
"const": "blocked"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"valid_input_and_current_state"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"local_internal_draft"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"internal_evidence_plan"
]
},
"availability": {
"const": "draft_only_no_external_effect"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"human_review_of_unknowns"
]
}
}
}
}
}
],
"required": [
"contract_version",
"decision_state",
"next_safe_action",
"stop",
"allowed_effects",
"forbidden_effects",
"max_capital_commitment_usd",
"external_contact_allowed",
"customer_launch_allowed",
"revalidate_before_effect",
"historical_output_is_not_current_permission",
"execution_authorized",
"external_action_authorized",
"capability_issued"
],
"properties": {
"stop": {
"type": "object",
"required": [
"required",
"applies_to",
"analytical_chain_required",
"reason_codes",
"unknown_risks_remain"
],
"properties": {
"required": {
"const": true
},
"applies_to": {
"const": "all_consequential_external_actions"
},
"reason_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"unknown_risks_remain": {
"const": true
},
"analytical_chain_required": {}
},
"additionalProperties": false
},
"decision_state": {},
"allowed_effects": {},
"contract_version": {
"const": "mvr.preflight-action-boundary/1"
},
"next_safe_action": {
"type": "object",
"required": [
"type",
"availability",
"required_host_inputs",
"handoff_source"
],
"properties": {
"type": {},
"availability": {},
"handoff_source": {},
"required_host_inputs": {}
},
"additionalProperties": false
},
"capability_issued": {
"const": false
},
"forbidden_effects": {
"const": [
"spend",
"external_contact",
"contract",
"customer_launch",
"pilot_execution",
"payment",
"deployment"
]
},
"execution_authorized": {
"const": false
},
"customer_launch_allowed": {
"const": false
},
"external_contact_allowed": {
"const": false
},
"revalidate_before_effect": {
"const": true
},
"external_action_authorized": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
},
"historical_output_is_not_current_permission": {
"const": true
}
},
"additionalProperties": false
},
"evidence_intake": {
"type": "object",
"properties": {
"status": {
"enum": [
"invalid_submission",
"described_not_structured",
"no_evidence_supplied",
"structured_items_supplied",
"mixed_descriptions_and_structured_items"
],
"type": "string"
},
"boundary": {
"type": "string",
"description": "Intake format is not evidence assessment."
},
"contract_version": {
"type": "string",
"description": "Intake disclosure version."
},
"structured_item_count": {
"type": "integer"
},
"evidence_count_semantics": {
"type": "string",
"description": "Counts submitted entries, not underlying records or verified sources."
},
"underlying_records_checked": {
"type": "boolean"
},
"content_assessment_performed": {
"type": "boolean"
},
"source_authenticity_verified": {
"type": "boolean"
},
"unstructured_description_count": {
"type": "integer"
}
}
},
"review_progress": {
"type": "object",
"properties": {
"contract_version": {
"const": "mvr.review-progress/1"
},
"scoring_eligible": {
"const": false
},
"execution_authorized": {
"const": false
},
"external_action_authorized": {
"const": false
}
},
"description": "Current case-bound review progress and residual risks. Internal evidence planning may be explicitly unreviewed; pilot designs and review packets require a separate scoped account review. No scoring, source truth or external-action permission.",
"additionalProperties": true
},
"safe_inferences": {
"type": "array",
"items": {
"type": "string"
}
},
"workflow_status": {
"type": "string"
},
"decision_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_recovery": {
"type": "object",
"properties": {
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
}
}
},
"unsafe_inferences": {
"type": "array",
"items": {
"type": "string"
}
},
"receipt_validation": {
"type": "object",
"properties": {
"expiry": {
"enum": [
"unknown"
],
"type": "string"
},
"status": {
"enum": [
"not_checked"
],
"type": "string"
},
"validity": {
"enum": [
"unknown"
],
"type": "string"
},
"performed": {
"enum": [
false
],
"type": "boolean"
},
"revocation": {
"enum": [
"unknown"
],
"type": "string"
}
}
},
"permission_position": {
"type": "object",
"properties": {
"tier": {
"enum": [
"prohibited",
"not_permitted",
"planning_only",
"not_applicable"
]
},
"scope": {
"const": "analysis_output"
},
"blocking_gates": {
"type": "array"
},
"contract_version": {
"const": "mvr.permission-position/1"
},
"external_effects": {
"type": "string"
},
"analysis_use_status": {
"type": "string"
},
"execution_authorized": {
"const": false
},
"narrowest_allowed_now": {
"type": "array"
},
"all_listed_gates_must_clear": {
"type": "boolean"
},
"cannot_change_the_claim_review": {
"type": [
"object",
"null"
]
}
},
"description": "Analysis-level permission position: level, what may proceed internally, every blocking gate (all must clear), decisive reviews for the claim gate (each item holding it and the act that clears it) and the evidence whose review cannot clear it. External effects are evaluated only by /v1/authority-chain check_permission. Never execution permission."
},
"workflow_expires_at": {
"type": [
"string",
"null"
]
},
"domain_routing_basis": {
"type": "string",
"description": "Routing basis, not a verified classification."
},
"evidence_field_guide": {
"type": "string",
"description": "Self-contained public evidence field types and unknown-metadata policy. Formatting guidance, not verification or authority."
},
"external_use_ceiling": {
"type": "object",
"required": [
"external_use_allowed",
"capability_issued"
],
"properties": {
"capability_issued": {
"const": false
},
"external_use_allowed": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
}
}
},
"mvr_response_receipt": {
"type": "object",
"required": [
"receipt_schema_version",
"mcp_tool",
"core_api_version",
"mcp_protocol_versions",
"mcp_contract_version",
"tool_profile_version",
"sdk_version",
"policy_version",
"calibration_version",
"deployment_revision",
"host_recipe_version",
"authority_boundary"
],
"properties": {
"mcp_tool": {
"type": "string"
},
"sdk_version": {
"type": "string"
},
"policy_version": {
"type": "string"
},
"core_api_version": {
"type": "string"
},
"authority_boundary": {
"type": "string"
},
"calibration_version": {
"type": "string"
},
"deployment_revision": {
"type": "string"
},
"host_recipe_version": {
"type": "string"
},
"mcp_contract_version": {
"type": "string"
},
"tool_profile_version": {
"type": "string"
},
"mcp_protocol_versions": {
"type": "array",
"items": {
"type": "string"
}
},
"receipt_schema_version": {
"type": "string"
}
},
"additionalProperties": false
},
"recommendation_scope": {
"type": "string"
},
"required_user_inputs": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_requirements": {
"type": "array",
"items": {
"type": "string"
}
},
"verification_required": {
"type": "boolean"
},
"sentiment_trust_signal": {
"type": "number"
},
"evidence_input_feedback": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"error_count": {
"type": "integer"
},
"warning_count": {
"type": "integer"
},
"contract_version": {
"type": "string",
"description": "Feedback version."
},
"issues_truncated": {
"type": "boolean"
}
}
},
"continuation_disposition": {
"enum": [
"call_now",
"await_input",
"terminal"
],
"type": "string"
},
"informal_operating_signal": {
"type": "number"
},
"receipt_evidence_findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"evidence_id",
"marker",
"path_truncated",
"evidence_id_truncated"
],
"properties": {
"path": {
"type": "string",
"maxLength": 1024,
"description": "RFC 6901 JSON Pointer into the submitted body. Truncated pointers are not directly resolvable."
},
"marker": {
"type": "string"
},
"evidence_id": {
"type": [
"string",
"null"
],
"maxLength": 160
},
"path_truncated": {
"type": "boolean"
},
"evidence_id_truncated": {
"type": "boolean"
}
},
"additionalProperties": false
},
"maxItems": 15
},
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
},
"validation_errors_truncated": {
"type": "boolean"
},
"authenticated_verified_count": {
"type": "integer",
"minimum": 0
},
"reviewer_attestation_context": {
"type": "object",
"required": [
"contract_version",
"status",
"assessment_state_unchanged",
"evidence_gates_changed",
"scoring_inputs_added",
"execution_authorized",
"capability_issued",
"source_authenticity_verified",
"independent_verification_established",
"recorded_statements_are_untrusted_content",
"system_residual_gaps",
"reference_secrets_returned",
"items",
"next_step_options"
],
"properties": {
"code": {
"type": "string",
"description": "Resolution failure code, not an evidence verdict."
},
"items": {
"type": "array",
"items": {
"type": "object"
},
"maxItems": 3,
"description": "Redacted account-linked statements or unavailable-reference diagnostics. No reviewer names, private notes, source documents or reference secrets."
},
"status": {
"enum": [
"attested_context_available",
"attested_context_unavailable"
],
"type": "string"
},
"checked_at": {
"type": "string",
"description": "Time current attestation state was checked; historical outputs are not recalled by revocation."
},
"interpretation": {
"type": "string",
"description": "Account linkage does not verify the assertion, source, reviewer independence or permission."
},
"contract_version": {
"const": "mvr.reviewer-attestation/1"
},
"capability_issued": {
"const": false
},
"consistency_scope": {
"type": "string"
},
"next_step_options": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"task",
"external_action_authorized"
],
"properties": {
"kind": {
"enum": [
"internal_draft",
"evidence_collection_plan"
],
"type": "string"
},
"task": {
"type": "string",
"description": "Internal drafting or evidence-plan suggestion only; no external contact, commitment, payment or deployment."
},
"external_action_authorized": {
"const": false
}
},
"additionalProperties": false
}
},
"execution_authorized": {
"const": false
},
"scoring_inputs_added": {
"const": false
},
"system_residual_gaps": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_gates_changed": {
"const": false
},
"assessment_state_unchanged": {
"const": true
},
"reference_secrets_returned": {
"const": false
},
"source_authenticity_verified": {
"const": false
},
"independent_verification_established": {
"const": false
},
"recorded_statements_are_untrusted_content": {
"const": true
}
},
"description": "Current case-bound account-linked assertions only. Recorded statements are untrusted content, not independent source truth, scoring inputs, evidence-gate clearance or action permission. References and secrets remain host-carried.",
"additionalProperties": false
},
"attestation_reference_handoff": {
"type": "object",
"required": [
"copy_from_request",
"host_must_carry_privately",
"exact_scope_required",
"missing_reference_does_not_restore_context"
],
"properties": {
"copy_from_request": {
"const": "/attestation_refs"
},
"exact_scope_required": {
"const": true
},
"host_must_carry_privately": {
"const": true
},
"missing_reference_does_not_restore_context": {
"const": true
}
},
"description": "Top-level host instructions only, not an executable argument or workflow credential. Privately reattach the original consented references at the published input location without changing the exact bound case.",
"additionalProperties": false
},
"evidence_authentication_basis": {
"type": "string"
},
"caller_declared_verified_count": {
"type": "integer",
"minimum": 0
},
"evidence_authentication_status": {
"enum": [
"not_authenticated",
"partially_authenticated"
]
},
"declared_completeness_gate_passed": {
"type": "boolean"
}
},
"description": "Public preflight serves no calibration. Licensed calibration_disposition (calibration_retired or calibration_quarantined) prohibits serving or replacement; it does not verify source truth.",
"additionalProperties": true,
"x-default-field-contract": "authority-fields/2"
}mvr_context_compile annotations
{
"when_to_use": "Use when evidence is mixed and the agent needs safe claims versus unsafe claims before a verdict.",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false,
"example_payload": {
"subject": {
"entity_name": "Example Kenya retail platform",
"entity_archetype": "retail_chain"
},
"market_scope": {
"country": "KE"
},
"evidence_pack": [
{
"id": "EV-1",
"source_grade": "B",
"evidence_type": "registry_record"
},
{
"id": "EV-2",
"source_grade": "C",
"evidence_type": "field_observation"
}
]
},
"when_not_to_use": "Do not use as a go/no-go decision. Submit only consented, data-minimized, redacted or aggregated evidence; never raw confidential datasets, secrets, credentials, or personal identifiers.",
"example_response": {
"status": "compiled",
"safe_inferences": [
"Some evidence exists, but sandbox context should be treated as advisory."
],
"unsafe_inferences": [
"Do not claim credit approval, legal certification, or investment readiness from sandbox context."
],
"verification_required": true
},
"next_tool_to_call": "mvr_decision_check",
"commercial_boundary": "Sandbox context compilation is not board-safe or production-calibrated. Use a licensed key for strict-calibrated outputs.",
"required_payload_fields": [
"subject",
"market_scope",
"evidence_pack or evidence_items",
"evidence origin/source class where available"
]
}mvr_decision_check — Check evidence before MVR scoring
Advertised read-only
Use after evidence completeness to route a structurally complete pack toward licensed MVR scoring or abstain on missing proof. This public tool does not compute market, pilot, or scale readiness. Use when: Use after evidence completeness to determine whether the pack can be routed to licensed MVR scoring or still requires proof. Do not use when: Do not use as readiness, pilot, credit, legal, regulatory, or scale authorization. Submit only consented, data-minimized, redacted or aggregated evidence; never secrets, credentials, or personal identifiers. Evidence input location: arguments.payload. evidence_pack: object array. String fields: evidence_type, source_class, stakeholder_class, verification_status, source_date, source_doc_id. geography: string/object; evidence_geography: object; district: nonblank string; districts: nonblank strings array. source_date/freshness_date: YYYY, YYYY-MM, YYYY-MM-DD or ISO timestamp with timezone. source_date_range: {earliest,latest}, same-precision ordered bounds within supplied dates. analysis_date stays exact. Intervals have age_days:null and age_days_min/max; unresolved window/future overlap excludes coverage. Omit unknown dates/references, never null or invented. verification_status: unverified if unchecked. *_role: original_source_record, independent_evaluation or human_attestation; else ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. collection_context + provenance_ledger: see schema/feedback. Keep adverse facts; never relabel to pass.
mvr_decision_check input schema
{
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"properties": {
"stage": {
"type": "string",
"description": "Free-text venture stage, for example pre-MVP, pilot, grant-funded programme or scaling. No closed enum."
},
"claims": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"claim"
],
"properties": {
"claim": {
"type": "string",
"description": "Minimal public-safe target proposition."
},
"claim_id": {
"type": "string",
"description": "Opaque claim identifier."
},
"support_links": {
"type": "array",
"items": {
"type": "object",
"required": [
"claim_id",
"evidence_id",
"relationship",
"locator"
],
"properties": {
"locator": {
"type": "string",
"description": "Specific page, cell or section. A locator is not proof."
},
"claim_id": {
"type": "string",
"description": "Must match the containing claim."
},
"evidence_id": {
"type": "string",
"description": "Must identify an item in this complete evidence pack."
},
"relationship": {
"enum": [
"direct_support",
"qualifies",
"contradicts",
"context_only"
],
"type": "string"
},
"review_event_id": {
"type": "string",
"description": "Only the licensed review service can check this event; ignored as authority by public preflight."
}
}
}
}
}
},
"description": "Optional explicit target claims and source-specific support links. Reuses the governed claim-audit vocabulary. Public links are caller declarations, never authenticated reviewer attestations."
},
"subject": {
"type": "object",
"properties": {
"sector": {
"type": "string"
},
"entity_id": {
"type": "string"
},
"entity_name": {
"type": "string"
},
"entity_archetype": {
"type": "string"
}
},
"description": "Resolved or supplied entity under assessment.",
"additionalProperties": true
},
"target_use": {
"type": "string",
"description": "Internal planning, pilot design, customer-facing, investor-facing, or rollout use."
},
"market_scope": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared target city."
},
"region": {
"type": "string",
"description": "Declared target region."
},
"country": {
"type": "string",
"description": "Declared target country, not the source country."
},
"corridor": {
"type": "string",
"description": "Declared target corridor."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank target district; not verified source coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Target districts as nonblank strings; empty is allowed but does not declare subnational scope."
},
"town_or_zone": {
"type": "string",
"description": "Declared target town or zone."
},
"micro_context": {
"type": "string",
"description": "Explicit local decision context."
},
"decision_scope_level": {
"enum": [
"country",
"subnational"
],
"type": "string",
"description": "Explicit decision scope. Subnational needs declared locality. A country-only decision must be declared, not inferred from absent districts."
}
},
"description": "Declared decision geography, not source geography. Supply district/districts or decision_scope_level country/subnational; subnational requires locality. A bounded Uganda target-name cross-check can require scope review, never insert districts or establish field coverage.",
"additionalProperties": true
},
"target_claim": {
"type": "string",
"description": "Exact claim or readiness question to authorize, limit, or abstain on."
},
"analysis_date": {
"type": "string",
"description": "Optional YYYY-MM-DD or ISO timestamp with timezone, no later than today in analysis_timezone (UTC by default). Defaults to the current date in that calendar. Carried through the public handoff."
},
"evidence_pack": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Full current evidence pack. Rechecks replace the pack; the server does not append or retrieve evidence."
},
"decision_stage": {
"type": "string",
"description": "Idea, pre-entry, pilot, launch, expansion, or scale stage."
},
"evidence_items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Optional item identifier. Does not establish a distinct source."
},
"claim": {
"type": "string",
"description": "Minimal, non-confidential claim supported by the item; do not send raw private interviews."
},
"status": {
"type": "string",
"description": "Legacy alias for verification_status."
},
"geography": {
"type": [
"string",
"object"
],
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"description": "Source country name/code or broader description, or an object with country, city, region and town_or_zone strings, a nonblank district string and a districts array of nonblank strings (empty allowed). Known country conflicts, including conflicting evidence_geography.country, are flagged; local applicability is not authenticated.",
"additionalProperties": true
},
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual sample size; required for collector-administered modes, including groups. Group sample cannot exceed session_count times participants_per_session. All supplied aliases must agree; never invent a sample for documentary or self-administered evidence."
},
"source_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"source_hash": {
"type": "string",
"description": "Optional SHA-256 source hash, 64 hexadecimal characters; a hash does not authenticate its origin."
},
"load_bearing": {
"type": "boolean",
"description": "True if the target recommendation materially depends on this item."
},
"source_class": {
"type": "string",
"description": "Origin label, for example entity_reported, regulator_published, structured_field_research, operational_data or counterparty_reference. model_inferred is not source evidence and is rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Never relabel it to pass. Origin is not a claim of independence."
},
"source_grade": {
"type": "string",
"description": "Caller-supplied grade. Not a substitute for verification or source lineage."
},
"evidence_type": {
"type": "string",
"description": "What was collected, for example interview, field observation or licence record. Not merely the conclusion."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Compatibility origin label. Explicit field/public conflicts, including provenance_ledger.source_family, require reconciliation; one label cannot erase another."
},
"freshness_date": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Compatibility alias for source_date, at the same declared precision. Exact dates/timestamps may name the same analysis-calendar day; conflicting aliases require correction. No source truth is established."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"survey_payload": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
}
},
"description": "Existing sample_size alias; all supplied sample-size aliases must agree.",
"additionalProperties": true
},
"evidence_origin": {
"type": "string",
"description": "Declared source origin. Explicit public/documentary sources are not caller fieldwork solely because evidence_type is survey. Conflicting explicit field origins still block; never relabel to pass."
},
"is_load_bearing": {
"type": "boolean",
"description": "Compatibility alias for load_bearing."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"provenance_ledger": {
"type": "object",
"properties": {
"source_url": {
"type": "string",
"description": "Source reference only; the sandbox does not fetch or authenticate it."
},
"source_doc_id": {
"type": "string",
"description": "Opaque source-document reference, not an evidence-item ID or personal identifier."
},
"source_family": {
"type": "string",
"description": "Declared source family; distinct labels do not prove independence."
},
"source_locator": {
"type": "string",
"description": "Redacted document-specific locator, not the shared folder holding unrelated documents. Never invent a locator. Genuine shared upstream references count together."
},
"synthetic_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "Source-reference fields that were generated rather than observed; these do not establish lineage."
},
"parent_source_ids": {
"type": "array",
"items": {
"type": "string"
}
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
}
},
"description": "Field evidence needs source_doc_id and an explicit parent_source_ids array (empty allowed). Unknown lineage stays incomplete, not invented.",
"additionalProperties": true
},
"source_date_range": {
"type": "object",
"required": [
"earliest",
"latest"
],
"properties": {
"latest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
},
"earliest": {
"type": "string",
"maxLength": 32,
"minLength": 4,
"description": "Declared source date at its actual precision: YYYY, YYYY-MM, YYYY-MM-DD, or ISO timestamp with seconds and timezone (up to 6 fractional digits). Years 0001-9999; real calendar dates only. Partial dates describe inclusive calendar bounds, never an invented day. Source truth and current applicability remain unverified."
}
},
"description": "Optional inclusive declared bounds, usable without source_date. Both endpoints must have the same precision and be ordered. Every supplied source_date/freshness_date must contain the whole range; an exact timestamp cannot be widened. Aliases must agree before narrowing. Unknown dates are not clipped to the analysis date. Bounds are declarations, not source verification.",
"additionalProperties": false
},
"stakeholder_class": {
"type": "string",
"description": "Role represented, for example guardian, customer, supplier or partner. Do not submit a person identifier."
},
"collection_context": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"source_extraction": {
"type": "object",
"required": [
"source_ref",
"fields"
],
"properties": {
"fields": {
"type": "object",
"properties": {
"sample_size": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"session_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Actual number of group sessions in the source records."
},
"interview_mode": {
"enum": [
"face_to_face",
"telephone",
"online",
"focus_group",
"group_interview",
"observation",
"administrative_record",
"unknown"
],
"type": "string"
},
"source_modality": {
"enum": [
"direct_observation",
"documentary",
"secondary_summary",
"unknown"
],
"type": "string"
},
"enumerator_count": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"additionalProperties": false
},
"source_ref": {
"type": "string",
"maxLength": 512,
"minLength": 1
}
},
"description": "Optional caller-supplied second reading of source facts for conflict comparison only. Not independently authenticated; cannot supply missing primary declarations or establish source authenticity.",
"additionalProperties": false
},
"reviewer_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collector_relationship": {
"enum": [
"independent",
"employee",
"company_staff",
"internal",
"contractor",
"partner",
"self_collected",
"unknown"
],
"type": "string"
},
"collectors_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Collectors required concurrently for each group session, drawn from enumerator_count. No default facilitator count is assumed."
},
"fieldwork_window_minutes": {
"type": "number",
"description": "Total available collection minutes per collector across the entire period, not daily or team-person-minutes.",
"exclusiveMinimum": 0
},
"participants_per_session": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": 1,
"description": "Source-grounded maximum participants in any session. Sample size cannot exceed session_count times this bound; no default group size is assumed."
},
"session_duration_minutes": {
"type": "number",
"description": "Source-recorded duration of each group session in this declaration, not an alias for individual interview duration.",
"exclusiveMinimum": 0
},
"collection_administration": {
"enum": [
"collector_administered",
"self_administered",
"automated",
"unknown"
],
"type": "string",
"description": "Source-grounded administration, required for online, observation and administrative_record modes. self_administered is supported for online; automated for observation or administrative_record. Face-to-face, telephone and group modes are collector-administered and cannot opt out."
},
"interview_duration_minutes": {
"type": "number",
"description": "Collector time per individual interview or per observed/processed sample record for collector-administered non-group modes.",
"exclusiveMinimum": 0
}
},
"description": "Source-grounded collection declarations, not source authentication. Unknown facts must remain missing; do not invent values to pass. Field decision use requires source modality, collector relationship, interview mode, source-document identity and an explicit parent-source list. Collector-administered modes require staffing, duration, available minutes per collector and sample size. Group modes additionally require session_count, participants_per_session, session_duration_minutes and collectors_per_session, never inferred from an individual interview duration. Online, observation and administrative_record modes require collection_administration; self-administered online and automated observation/record sources do not need invented collector capacity. Explicit public/documentary origins are not caller fieldwork solely because evidence_type is survey; conflicting explicit field origins still block. Independent verification labels require a separate reviewer relationship; persisted review is still checked separately.",
"additionalProperties": true
},
"evidence_geography": {
"type": "object",
"properties": {
"city": {
"type": "string",
"description": "Declared source city."
},
"region": {
"type": "string",
"description": "Declared source region."
},
"country": {
"type": "string",
"description": "Declared source country, not the target country."
},
"district": {
"type": "string",
"pattern": "\\S",
"description": "Nonblank declared source district, not verified local coverage."
},
"districts": {
"type": "array",
"items": {
"type": "string",
"pattern": "\\S"
},
"description": "Declared source districts, each a nonblank string. An empty array is allowed. Not verified fieldwork or representative coverage."
},
"town_or_zone": {
"type": "string",
"description": "Declared source town or zone."
}
},
"additionalProperties": true
},
"upstream_source_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "Disclose shared upstream sources; distinct identifiers do not prove independence."
},
"verification_status": {
"type": "string",
"description": "Caller label. verified, independently_verified, corroborated, attested, confirmed and validated count for the structural prefilter only. self_attested, unverified, missing and other labels do not. Do not change labels without actually checking the source."
}
},
"description": "A caller-declared, consented and redacted evidence item. No required fields at intake: incomplete items receive correction feedback. Explicit artifact_role, evidence_role, source_role, record_role and content_role declarations admit only original_source_record, independent_evaluation or human_attestation; other declared roles are rejected with ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. Omission remains supported for legacy items. Passing coverage never verifies truth, permission or readiness.",
"additionalProperties": true
},
"description": "Alias for evidence_pack. Supply one field, not conflicting copies."
},
"review_case_ref": {
"type": "object",
"required": [
"case_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"writeOnly": true,
"properties": {
"case_id": {
"type": "string",
"pattern": "^RC-[a-f0-9]{64}$"
},
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true
}
},
"description": "Host-private, case-bound read reference. Never put its secret into prompts, URLs, logs or exports. Grants no write or action authority.",
"additionalProperties": false
},
"attestation_refs": {
"type": "array",
"items": {
"type": "object",
"required": [
"attestation_id",
"tenant_id",
"workspace_id",
"reference_secret"
],
"properties": {
"tenant_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"workspace_id": {
"type": "string",
"maxLength": 200,
"minLength": 1
},
"attestation_id": {
"type": "string",
"pattern": "^ATT-[a-f0-9]{64}$"
},
"reference_secret": {
"type": "string",
"pattern": "^[a-f0-9]{64}$",
"writeOnly": true,
"description": "256-bit random bearer secret. Keep host-private, out of URLs/logs/prompts/exports; grants shared context, not authority."
}
},
"additionalProperties": false
},
"maxItems": 3,
"writeOnly": true,
"description": "Optional: https://africanmarketos.com/v1/reviewer-attestations/contract. Requires exact subject, market_scope.country and decision_question. Host-private refs outside evidence; reattach each call. No scoring or authority."
},
"analysis_timezone": {
"type": "string",
"description": "Optional IANA timezone, for example Africa/Nairobi, for the analysis calendar. Defaults to UTC; never inferred from country or IP. Date-only values keep their declared calendar day."
},
"decision_question": {
"type": "string",
"maxLength": 2000,
"description": "Exact recorded attestation question; question must agree when supplied."
},
"evidence_available": {
"type": "array",
"items": {
"type": "string"
},
"description": "Short optional context labels, not proof. For supplied document summaries use incomplete evidence_pack items instead; do not mark claims verified merely because a document exists."
},
"context_freshness_window_days": {
"type": "integer",
"minimum": 1,
"description": "Optional caller-declared maximum evidence age in days. No universal freshness cutoff is invented when absent; age alone does not prove validity."
}
},
"description": "Decision question, resolved subject, market scope, and evidence for a bounded recommendation or abstention.",
"additionalProperties": true
}
},
"additionalProperties": false
}mvr_decision_check output schema
{
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"reason": {
"type": "string"
},
"status": {
"type": "string"
},
"next_steps": {
"type": "object",
"required": [
"schema_version",
"purpose",
"automatic_action_authorized",
"boundary",
"offer_registry",
"options"
],
"properties": {
"options": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"label",
"url",
"when_to_use"
],
"properties": {
"id": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"label": {
"type": "string"
},
"when_to_use": {
"type": "string"
}
},
"additionalProperties": false
},
"maxItems": 3
},
"purpose": {
"type": "string",
"const": "optional_routing_not_recommendation"
},
"boundary": {
"type": "string"
},
"offer_registry": {
"type": "string",
"format": "uri"
},
"schema_version": {
"type": "string",
"const": "mvr-optional-routing@1.0"
},
"automatic_action_authorized": {
"type": "boolean",
"const": false
}
},
"additionalProperties": false
},
"workflow_id": {
"type": [
"string",
"null"
]
},
"claim_review": {
"type": "object",
"properties": {
"links": {
"type": "array",
"items": {
"type": "object"
}
},
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"status": {
"type": "string"
},
"blocking": {
"type": "boolean"
},
"boundary": {
"type": "string"
},
"claim_count": {
"type": "integer"
},
"linkage_gaps": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"content_item_count": {
"type": "integer"
},
"unlinked_claim_count": {
"type": "integer"
},
"linkage_gaps_truncated": {
"type": "boolean"
},
"unlinked_evidence_count": {
"type": "integer"
},
"content_assessment_performed": {
"type": "boolean"
},
"declared_contradiction_count": {
"type": "integer"
},
"declared_qualification_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"evidence_fit": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"blocking": {
"type": "boolean"
},
"analysis_date": {
"type": "string"
},
"decision_scope": {
"type": "object",
"properties": {
"level": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"declared",
"unresolved",
"not_requested"
],
"type": "string"
},
"missing_fields": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"analysis_timezone": {
"type": [
"string",
"null"
]
},
"coverage_exclusion_count": {
"type": "integer"
},
"source_authenticity_verified": {
"type": "boolean"
}
}
},
"total_errors": {
"type": "integer",
"minimum": 0
},
"evidence_gaps": {
"type": "array",
"items": {
"type": "string"
}
},
"mcp_next_call": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"name",
"arguments"
],
"properties": {
"name": {
"type": "string"
},
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
]
},
"mcp_next_tool": {
"anyOf": [
{
"type": "null"
},
{
"type": "object",
"required": [
"tool_name",
"arguments"
],
"properties": {
"arguments": {
"type": "object",
"required": [
"payload"
],
"properties": {
"payload": {
"type": "object",
"additionalProperties": true
}
},
"additionalProperties": false
},
"tool_name": {
"type": "string"
}
},
"additionalProperties": false
}
]
},
"not_a_verdict": {
"type": "boolean"
},
"response_meta": {
"type": "object"
},
"source_review": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"type": "object"
}
},
"status": {
"type": "string"
},
"evidence_strength": {
"type": [
"number",
"null"
]
},
"required_before_consequential_reliance": {
"type": "boolean"
}
}
},
"recommendation": {
"type": "string"
},
"action_boundary": {
"type": "object",
"oneOf": [
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": false
}
}
},
"decision_state": {
"enum": [
"assessment_in_progress"
]
},
"allowed_effects": {
"const": [
"read_only_assessment"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"continue_evidence_assessment"
]
},
"availability": {
"const": "exact_server_handoff"
},
"handoff_source": {
"const": "mcp_next_call"
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"versioned_internal_plan"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"evidence_collection_design",
"internal_pilot_design"
]
},
"availability": {
"const": "authenticated_case_handoff"
},
"handoff_source": {
"const": "review_progress.bounded_next_actions"
},
"required_host_inputs": {
"const": [
"current_case",
"expected_revision",
"operation_id"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"outside_declared_mvr_scope"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"ordinary_task_outside_mvr"
]
},
"availability": {
"const": "routing_only_not_permission"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": []
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"blocked_invalid_or_unavailable"
]
},
"allowed_effects": {
"const": []
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"correct_input_or_restore_current_state"
]
},
"availability": {
"const": "blocked"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"valid_input_and_current_state"
]
}
}
}
}
},
{
"properties": {
"stop": {
"properties": {
"analytical_chain_required": {
"const": true
}
}
},
"decision_state": {
"enum": [
"abstain_pending_evidence",
"assessment_completed"
]
},
"allowed_effects": {
"const": [
"local_internal_draft"
]
},
"next_safe_action": {
"properties": {
"type": {
"enum": [
"internal_evidence_plan"
]
},
"availability": {
"const": "draft_only_no_external_effect"
},
"handoff_source": {
"const": null
},
"required_host_inputs": {
"const": [
"human_review_of_unknowns"
]
}
}
}
}
}
],
"required": [
"contract_version",
"decision_state",
"next_safe_action",
"stop",
"allowed_effects",
"forbidden_effects",
"max_capital_commitment_usd",
"external_contact_allowed",
"customer_launch_allowed",
"revalidate_before_effect",
"historical_output_is_not_current_permission",
"execution_authorized",
"external_action_authorized",
"capability_issued"
],
"properties": {
"stop": {
"type": "object",
"required": [
"required",
"applies_to",
"analytical_chain_required",
"reason_codes",
"unknown_risks_remain"
],
"properties": {
"required": {
"const": true
},
"applies_to": {
"const": "all_consequential_external_actions"
},
"reason_codes": {
"type": "array",
"items": {
"type": "string"
}
},
"unknown_risks_remain": {
"const": true
},
"analytical_chain_required": {}
},
"additionalProperties": false
},
"decision_state": {},
"allowed_effects": {},
"contract_version": {
"const": "mvr.preflight-action-boundary/1"
},
"next_safe_action": {
"type": "object",
"required": [
"type",
"availability",
"required_host_inputs",
"handoff_source"
],
"properties": {
"type": {},
"availability": {},
"handoff_source": {},
"required_host_inputs": {}
},
"additionalProperties": false
},
"capability_issued": {
"const": false
},
"forbidden_effects": {
"const": [
"spend",
"external_contact",
"contract",
"customer_launch",
"pilot_execution",
"payment",
"deployment"
]
},
"execution_authorized": {
"const": false
},
"customer_launch_allowed": {
"const": false
},
"external_contact_allowed": {
"const": false
},
"revalidate_before_effect": {
"const": true
},
"external_action_authorized": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
},
"historical_output_is_not_current_permission": {
"const": true
}
},
"additionalProperties": false
},
"evidence_intake": {
"type": "object",
"properties": {
"status": {
"enum": [
"invalid_submission",
"described_not_structured",
"no_evidence_supplied",
"structured_items_supplied",
"mixed_descriptions_and_structured_items"
],
"type": "string"
},
"boundary": {
"type": "string",
"description": "Intake format is not evidence assessment."
},
"contract_version": {
"type": "string",
"description": "Intake disclosure version."
},
"structured_item_count": {
"type": "integer"
},
"evidence_count_semantics": {
"type": "string",
"description": "Counts submitted entries, not underlying records or verified sources."
},
"underlying_records_checked": {
"type": "boolean"
},
"content_assessment_performed": {
"type": "boolean"
},
"source_authenticity_verified": {
"type": "boolean"
},
"unstructured_description_count": {
"type": "integer"
}
}
},
"review_progress": {
"type": "object",
"properties": {
"contract_version": {
"const": "mvr.review-progress/1"
},
"scoring_eligible": {
"const": false
},
"execution_authorized": {
"const": false
},
"external_action_authorized": {
"const": false
}
},
"description": "Current case-bound review progress and residual risks. Internal evidence planning may be explicitly unreviewed; pilot designs and review packets require a separate scoped account review. No scoring, source truth or external-action permission.",
"additionalProperties": true
},
"workflow_status": {
"type": "string"
},
"decision_domains": {
"type": "array",
"items": {
"type": "string"
}
},
"safe_next_action": {
"type": "string"
},
"evidence_recovery": {
"type": "object",
"properties": {
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
}
}
},
"receipt_validation": {
"type": "object",
"properties": {
"expiry": {
"enum": [
"unknown"
],
"type": "string"
},
"status": {
"enum": [
"not_checked"
],
"type": "string"
},
"validity": {
"enum": [
"unknown"
],
"type": "string"
},
"performed": {
"enum": [
false
],
"type": "boolean"
},
"revocation": {
"enum": [
"unknown"
],
"type": "string"
}
}
},
"verification_basis": {
"type": "string"
},
"permission_position": {
"type": "object",
"properties": {
"tier": {
"enum": [
"prohibited",
"not_permitted",
"planning_only",
"not_applicable"
]
},
"scope": {
"const": "analysis_output"
},
"blocking_gates": {
"type": "array"
},
"contract_version": {
"const": "mvr.permission-position/1"
},
"external_effects": {
"type": "string"
},
"analysis_use_status": {
"type": "string"
},
"execution_authorized": {
"const": false
},
"narrowest_allowed_now": {
"type": "array"
},
"all_listed_gates_must_clear": {
"type": "boolean"
},
"cannot_change_the_claim_review": {
"type": [
"object",
"null"
]
}
},
"description": "Analysis-level permission position: level, what may proceed internally, every blocking gate (all must clear), decisive reviews for the claim gate (each item holding it and the act that clears it) and the evidence whose review cannot clear it. External effects are evaluated only by /v1/authority-chain check_permission. Never execution permission."
},
"workflow_expires_at": {
"type": [
"string",
"null"
]
},
"domain_routing_basis": {
"type": "string",
"description": "Routing basis, not a verified classification."
},
"evidence_field_guide": {
"type": "string",
"description": "Self-contained public evidence field types and unknown-metadata policy. Formatting guidance, not verification or authority."
},
"external_use_ceiling": {
"type": "object",
"required": [
"external_use_allowed",
"capability_issued"
],
"properties": {
"capability_issued": {
"const": false
},
"external_use_allowed": {
"const": false
},
"max_capital_commitment_usd": {
"const": 0
}
}
},
"mvr_response_receipt": {
"type": "object",
"required": [
"receipt_schema_version",
"mcp_tool",
"core_api_version",
"mcp_protocol_versions",
"mcp_contract_version",
"tool_profile_version",
"sdk_version",
"policy_version",
"calibration_version",
"deployment_revision",
"host_recipe_version",
"authority_boundary"
],
"properties": {
"mcp_tool": {
"type": "string"
},
"sdk_version": {
"type": "string"
},
"policy_version": {
"type": "string"
},
"core_api_version": {
"type": "string"
},
"authority_boundary": {
"type": "string"
},
"calibration_version": {
"type": "string"
},
"deployment_revision": {
"type": "string"
},
"host_recipe_version": {
"type": "string"
},
"mcp_contract_version": {
"type": "string"
},
"tool_profile_version": {
"type": "string"
},
"mcp_protocol_versions": {
"type": "array",
"items": {
"type": "string"
}
},
"receipt_schema_version": {
"type": "string"
}
},
"additionalProperties": false
},
"recommendation_scope": {
"type": "string"
},
"required_user_inputs": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_requirements": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_input_feedback": {
"type": "object",
"properties": {
"issues": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Codes: FIELD_PROVENANCE_REQUIRED,FIELD_PROVENANCE_CONFLICT,FIELDWORK_CAPACITY_CONTRADICTION,SOURCE_INDEPENDENCE_CONTRADICTION,SOURCE_VERIFICATION_CONTRADICTION,FIELD_SOURCE_MODALITY_CONFLICT,DECISION_GEOGRAPHY_SCOPE_REQUIRED,DECISION_SCOPE_REQUIRED,DECISION_SCOPE_REVIEW_REQUIRED,DECISION_SCOPE_CROSS_CHECK_LIMIT,SOURCE_EXTRACTION_INVALID,SOURCE_EXTRACTION_REFERENCE_CONFLICT,ADVERSE_SOURCE_REVIEW_REQUIRED,INVALID_CLAIM_INPUT,OUTPUT_RECEIPT_NOT_REQUEST_AUTHORITY,ARTIFACT_ROLE_NOT_SOURCE_EVIDENCE. HTTP 422: details/validation_errors; fix missing_fields. Never invent facts. These codes do not authenticate sources or authorize action. /docs/mcp-integration.md."
},
"path": {
"type": "string",
"description": "Indexed submitted payload path."
},
"message": {
"type": "string",
"description": "Correction without echoing source content."
},
"blocking": {
"type": "boolean"
},
"severity": {
"type": "string"
},
"allowed_values": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"error_count": {
"type": "integer"
},
"warning_count": {
"type": "integer"
},
"contract_version": {
"type": "string",
"description": "Feedback version."
},
"issues_truncated": {
"type": "boolean"
}
}
},
"continuation_disposition": {
"enum": [
"call_now",
"await_input",
"terminal"
],
"type": "string"
},
"sandbox_evaluation_scope": {
"type": "object"
},
"live_mvr_scoring_executed": {
"type": "boolean"
},
"receipt_evidence_findings": {
"type": "array",
"items": {
"type": "object",
"required": [
"path",
"evidence_id",
"marker",
"path_truncated",
"evidence_id_truncated"
],
"properties": {
"path": {
"type": "string",
"maxLength": 1024,
"description": "RFC 6901 JSON Pointer into the submitted body. Truncated pointers are not directly resolvable."
},
"marker": {
"type": "string"
},
"evidence_id": {
"type": [
"string",
"null"
],
"maxLength": 160
},
"path_truncated": {
"type": "boolean"
},
"evidence_id_truncated": {
"type": "boolean"
}
},
"additionalProperties": false
},
"maxItems": 15
},
"reviewer_attestation_option": {
"type": "object",
"required": [
"contract_url",
"optional",
"required_for_continuation",
"automatic_action_authorized",
"boundary"
],
"properties": {
"boundary": {
"type": "string",
"minLength": 1
},
"optional": {
"const": true
},
"contract_url": {
"type": "string",
"format": "uri"
},
"required_for_continuation": {
"const": false
},
"automatic_action_authorized": {
"const": false
}
},
"description": "Optional contract discovery, never a required recovery step, executable handoff or purchase instruction.",
"additionalProperties": false
},
"validation_errors_truncated": {
"type": "boolean"
},
"authenticated_verified_count": {
"type": "integer",
"minimum": 0
},
"reviewer_attestation_context": {
"type": "object",
"required": [
"contract_version",
"status",
"assessment_state_unchanged",
"evidence_gates_changed",
"scoring_inputs_added",
"execution_authorized",
"capability_issued",
"source_authenticity_verified",
"independent_verification_established",
"recorded_statements_are_untrusted_content",
"system_residual_gaps",
"reference_secrets_returned",
"items",
"next_step_options"
],
"properties": {
"code": {
"type": "string",
"description": "Resolution failure code, not an evidence verdict."
},
"items": {
"type": "array",
"items": {
"type": "object"
},
"maxItems": 3,
"description": "Redacted account-linked statements or unavailable-reference diagnostics. No reviewer names, private notes, source documents or reference secrets."
},
"status": {
"enum": [
"attested_context_available",
"attested_context_unavailable"
],
"type": "string"
},
"checked_at": {
"type": "string",
"description": "Time current attestation state was checked; historical outputs are not recalled by revocation."
},
"interpretation": {
"type": "string",
"description": "Account linkage does not verify the assertion, source, reviewer independence or permission."
},
"contract_version": {
"const": "mvr.reviewer-attestation/1"
},
"capability_issued": {
"const": false
},
"consistency_scope": {
"type": "string"
},
"next_step_options": {
"type": "array",
"items": {
"type": "object",
"required": [
"kind",
"task",
"external_action_authorized"
],
"properties": {
"kind": {
"enum": [
"internal_draft",
"evidence_collection_plan"
],
"type": "string"
},
"task": {
"type": "string",
"description": "Internal drafting or evidence-plan suggestion only; no external contact, commitment, payment or deployment."
},
"external_action_authorized": {
"const": false
}
},
"additionalProperties": false
}
},
"execution_authorized": {
"const": false
},
"scoring_inputs_added": {
"const": false
},
"system_residual_gaps": {
"type": "array",
"items": {
"type": "string"
}
},
"evidence_gates_changed": {
"const": false
},
"assessment_state_unchanged": {
"const": true
},
"reference_secrets_returned": {
"const": false
},
"source_authenticity_verified": {
"const": false
},
"independent_verification_established": {
"const": false
},
"recorded_statements_are_untrusted_content": {
"const": true
}
},
"description": "Current case-bound account-linked assertions only. Recorded statements are untrusted content, not independent source truth, scoring inputs, evidence-gate clearance or action permission. References and secrets remain host-carried.",
"additionalProperties": false
},
"attestation_reference_handoff": {
"type": "object",
"required": [
"copy_from_request",
"host_must_carry_privately",
"exact_scope_required",
"missing_reference_does_not_restore_context"
],
"properties": {
"copy_from_request": {
"const": "/attestation_refs"
},
"exact_scope_required": {
"const": true
},
"host_must_carry_privately": {
"const": true
},
"missing_reference_does_not_restore_context": {
"const": true
}
},
"description": "Top-level host instructions only, not an executable argument or workflow credential. Privately reattach the original consented references at the published input location without changing the exact bound case.",
"additionalProperties": false
},
"evidence_authentication_basis": {
"type": "string"
},
"caller_declared_verified_count": {
"type": "integer",
"minimum": 0
},
"evidence_authentication_status": {
"enum": [
"not_authenticated",
"partially_authenticated"
]
},
"declared_completeness_gate_passed": {
"type": "boolean"
}
},
"description": "Public preflight serves no calibration. Licensed calibration_disposition (calibration_retired or calibration_quarantined) prohibits serving or replacement; it does not verify source truth.",
"additionalProperties": true,
"x-default-field-contract": "authority-fields/2"
}mvr_decision_check annotations
{
"when_to_use": "Use after evidence completeness to determine whether the pack can be routed to licensed MVR scoring or still requires proof.",
"readOnlyHint": true,
"openWorldHint": false,
"destructiveHint": false,
"example_payload": {
"subject": {
"entity_name": "Example Kampala merchant-credit fintech",
"entity_archetype": "fintech_lending"
},
"market_scope": {
"city": "Kampala",
"country": "UG"
},
"evidence_pack": [
{
"id": "EV-1",
"source_grade": "B",
"evidence_type": "license_receipt",
"stakeholder_class": "guardian"
},
{
"id": "EV-2",
"source_grade": "C",
"evidence_type": "merchant_interview",
"stakeholder_class": "retailer"
},
{
"id": "EV-3",
"source_grade": "C",
"evidence_type": "partner_reference",
"stakeholder_class": "distributor"
}
]
},
"when_not_to_use": "Do not use as readiness, pilot, credit, legal, regulatory, or scale authorization. Submit only consented, data-minimized, redacted or aggregated evidence; never secrets, credentials, or personal identifiers.",
"example_response": {
"reason": "Evidence is too thin to route to licensed scoring.",
"status": "evidence_routing",
"evidence_gaps": [
"Add formal guardian evidence and field proof before scoring."
],
"not_a_verdict": true,
"recommendation": "abstain_pending_evidence",
"live_mvr_scoring_executed": false
},
"next_tool_to_call": "Gather the missing proof, or route a structurally complete pack to the licensed MVR API strict decision check.",
"commercial_boundary": "Public MCP decision_check is a sandbox evidence-routing aid only. Production, customer-facing, investor, accelerator, NGO, DFI, enterprise, consulting, or repeated automated use of MVR API output requires licensed MVR API scoring. Separately commissioned human services use the canonical offer registry and Work With Us and do not inherently require an API key.",
"required_payload_fields": [
"subject.entity_name",
"subject.entity_archetype",
"market_scope.country",
"evidence_pack or compiled_evidence"
]
}Prompts
Not advertised
Resources
Not advertised
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 7279 ms
- 95th percentile latency
- 7279 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 7279 ms · metadata changed · 5 tool(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http mvr-api-mcp https://africanmarketos.com/mcp/preflightCodex
Codex configuration
codex mcp add mvr-api-mcp --url https://africanmarketos.com/mcp/preflightCursor
Cursor configuration
{
"mcpServers": {
"mvr-api-mcp": {
"url": "https://africanmarketos.com/mcp/preflight"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"mvr-api-mcp": {
"type": "streamableHttp",
"url": "https://africanmarketos.com/mcp/preflight",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"mvr-api-mcp": {
"type": "http",
"url": "https://africanmarketos.com/mcp/preflight"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http mvr-api-mcp https://africanmarketos.com/mcp/preflightClaude Desktop
Claude Desktop configuration
https://africanmarketos.com/mcp/preflightWindsurf
Windsurf configuration
{
"mcpServers": {
"mvr-api-mcp": {
"serverUrl": "https://africanmarketos.com/mcp/preflight"
}
}
}Let your agent find its tools
Find servers like MVR API MCP from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.