Grounding & Provenance¶

Simulations are only as credible as the numbers they are built from. SocioVerse makes provenance a first-class artifact: every load-bearing value in a study can be traced to a source, a proxy, or an openly declared assumption.

Looking for the events service or the persona pool?

External data services moved to their own page: External Capabilities.

The grounding sidecar¶

Every study carries grounding/grounding.json: a ledger of

facts — with sources, gathered by real-world search when the study is initialized (a search always runs at /sv-init);
implementation references — the modeling literature or prior systems a design choice leans on;
declared assumptions — everything load-bearing that could not be sourced.

Each entry has a basis: sourced, proxy, or assumed. The build stages consult and extend the ledger; the rule of the workflow is:

Ground before you invent. A load-bearing environment or population value cites a fact id or an assumption id. What can't be sourced is declared — never silently invented.

/sv-report renders the ledger as the report's data basis & references section, so a reader sees the evidence base next to the results. The sidecar rides along automatically with forks and version snapshots.

Document shape¶

key	contents
`facts`	id, claim, value, `basis`, `via` (how it was obtained: `web_search`, `event_service`, `provider`), source url + accessed date
`implementation_refs`	the paper or prior system a mechanism copies, and what was copied
`assumptions`	id, what is assumed, why it could not be sourced, how sensitive the result is to it
`method_notes`	free text about how this study was grounded — including the fork decision below

The helper the workflow uses is skills.sv_grounding (merge(...), method_notes=...); see the workflow helpers reference for the API.

Provenance, not runtime validation

Grounding is documentation with teeth-at-review-time, not a runtime constraint: the engine does not check your constants against the ledger. The contract is social and reviewable — every number is citable, and reviewers can see which basis each one rests on.

Forking: an explicit re-grounding decision¶

A Path-A fork copies the source study's grounding.json along with everything else. It does not silently inherit that grounding as still-valid. Before touching the fork's artifacts, /sv-init asks one question — do the fork's deltas need external data the inherited grounding doesn't already cover? — and commits to one of two answers:

decision	when	what happens
search	the delta introduces a new real-world claim (new region, period, shock magnitude, policy)	a fresh search runs; new facts/refs are added by id; inherited entries that still apply stay
inherit	a pure parameter variant — every delta stays inside the range the source already anchored	no new search; the inherited entries the deltas touch are re-checked and merged by id

Either way the choice is recorded in the sidecar's method_notes, with its reason:

from skills import sv_grounding

sv_grounding.merge(
    "studies/chicago_sez",
    method_notes="fork re-grounding: searched — 一次性 +20% 冲击幅度需真实调价案例支撑",
)
# or: method_notes="fork re-grounding: inherited — 纯参数变体，锚点沿用源研究"

The dashboard's references card surfaces this, so a reader can tell whether a fork re-searched or leaned on its parent — and why. The judgment is never skipped silently; for a deliberately stylized study the honest note is method_notes="stylized", not invented facts.

One principle ties it together¶

The runtime loop never fetches. Everything external is materialized at build time, with provenance recorded in the grounding sidecar. Runs are therefore self-contained: no network surprises mid-simulation, and every input a run saw is on disk, versioned with the study.