Technical reference

Whathappensify brings AI access, simulation, evidence-aware reasoning and human perspectives into one system. This reference opens up the technical work behind that design. It covers the rules that bound what a result can claim and the records behind a result. It also covers how concerns become computational rules, and the methods used to explore a place.

The working-platform screens and compiler-evaluated examples show the platform at work. The deeper references below give the full detail for readers who want to examine how the ideas take shape in software.

Explore the mechanisms

The simulation and assistant references are built from the platform's own registries, so they describe the models, techniques and operations it has. The EPM reference states the rules the platform applies to every result. The worked comparison is an illustrated example. The public simulation overview describes, in everyday terms, the questions people can bring and the models that address them.

How the parts fit together

A question passes through every part of the platform. Select a part to see what it does, or follow one question from start to finish.

Follow Rosa’s questionBackNext

Select a part to see what it does, or follow Rosa’s question through the platform.

Rosa’s question, step by step

1. Rosa asks her assistant which of three permitted spots suits her pupusa truck at lunchtime.
2. The assistant works out what the question needs: the streets around each spot, the hours, and who walks past.
3. It prepares a setup through the ten operations, its only way into the platform.
4. The question becomes a scenario: three spots, a weekday lunchtime, people walking past each one.
5. Rosa reviews the setup in her browser and approves it. Nothing is simulated until she does.
6. Public data about the streets, and what Rosa knows about her regular customers, feed the run.
7. Before the run, the EPM checks that every input is of a kind the operation accepts and that Rosa may use it.
8. The engine simulates people moving through the streets around each spot.
9. After the run, the EPM labels each result. A simulation run suggests; it does not predict sales.
10. Every step is recorded with its inputs, methods, assumptions and label.
11. Rosa watches the runs and compares the three spots side by side.
12. She reads the comparison through her own Perspective: what matters for her business.
13. Her assistant explains what the comparison supports, in the words its labels allow.
14. The decision stays with Rosa.

A result with an examinable basis

A retained result connects the question, scenario, inputs, methods and execution settings to the computation and its interpretation. Content digests identify the particular material used and make changes detectable. The record makes it possible to return to an assumption, examine a comparison and develop a linked alternative.

Reproducibility lets people check a calculation. Model validation examines its relationship to the world and the question being asked. A reproducible error remains an error. Keeping that distinction clear makes it possible to challenge a model while understanding precisely what it computed.

Operation type and claim strength

The Epistemic Protocol Machine (EPM) bounds what an AI assistant may claim from a result. It certifies that a claim does not reach beyond what its method and verified inputs license. It does not certify that a model is right about the world.

Every result that makes a claim carries a label with two parts. The grade names the kind of act: observe (OBS), interpret (INT), reason (RSN), recommend (ACT) or revise (LRN). OBS, INT and RSN form a chain. ACT and LRN both sit above RSN, but neither is above the other. A step that would combine them has no join and is refused.

Claim strength runs from CS0 to CS4, with a verb for each level: speculative, suggests, indicates, strongly indicates, demonstrates. These are ordered qualifications, not probabilities. Each grade admits only a window of strengths, from OBS at CS0 or CS1 to ACT at CS3 or CS4.

Each of the ten operations declares the grades it accepts and a ceiling on its label. Composition checks govern how operations connect. Fifteen of the hundred ordered pairs are refused before anything runs, with one narrow exception set out in the EPM reference. A type-compatible sequence is the beginning of a valid analysis; the methods, assumptions and evidence give its conclusion substance.

Within those bounds, each method carries a fixed label with a written rationale. A result receives that label only when the method's support is established; otherwise the request is refused, or a simulation run carries no claim. A qualified simulation method whose declared label is INT:CS1 returns “suggests” when its evidence requirements hold. An unreviewed authored model retains its calculations with no claim; successful numerical checks and approval to run do not supply scientific review. No method reaches CS4.

A label rests on the method, the provenance of its inputs and checks that the method applied to them. Model fidelity, the width of an uncertainty estimate and comparison with observed data do not enter it.

The public EPM explanation follows these ideas through an ordinary question. The EPM reference sets out every operation's contract, the composition rules and the limits.

Perspectives and evidence

A Perspective preserves a person's concern, the mapping that represents it, and the computational rule derived from that mapping. The Perspective compiler checks the translation and identifies matters requiring deliberation. Authored content and compiled rules have distinct identities so that people can examine which layer changed.

The following diagram uses the clinic-access illustration: residents compare a supplied set of road closures with an alternative that keeps one connection available. Distance, step-free access and the distribution of benefits express different concerns. These are illustrative points of view, not findings about a real community.

A completed result can be read through different Perspectives. Its calculated quantities and evidence remain fixed; a new concern can also motivate new evidence and another simulation. This keeps the relationship between human meaning, the representation and the computation available for examination.

Refusals, errors, and external explanations

The platform distinguishes a refusal from an execution error. A refusal records why a request cannot proceed under the evidence and authority rules. An execution error records a computation that failed. This allows the assistant and the person to decide whether to obtain evidence, revise the question or pursue another approach.

Every refusal carries a typed code, such as COMPOSITION_CHAIN_REFUSED or GUARD_REFUSED. The assistant also receives a structured explanation: the conditions that failed, drawn from a fixed vocabulary, and the steps that would remedy them. Identities of the cited evidence are withheld, so a refusal cannot reveal records the person may not see.

A run can also succeed without a claim. When a step cannot establish that its method applied, the run keeps its numbers, carries no label and states why. A refusal is never evidence for a later claim. Publication is atomic. A result identifies unfinished or failed members and the evidence included in each summary; incomplete work is never presented as a completed experiment.

An external AI assistant explains the platform's results in ordinary language. The retained record provides a basis for checking that explanation. Human approval, access permissions and decisions about publication remain explicit parts of the work.

Evaluation and independent operation

Comparison with observed data runs on a separate validation track, using thresholds from the published literature. A person approves each comparison before its outcome is shown. Validation results are recorded separately and never change a label. A result withdrawn as evidence, or one resting on a source whose access has been revoked, cannot support a new claim.

The architecture connects a Rust simulation engine, a Python software development kit (SDK), an MCP interface for assistants and a browser experience for people. The SDK provides the broader development surface; assistants reach the platform through MCP and its evidence and authority controls.

Whathappensify is open source. Independent installation, examination and extension support its purpose as digital public infrastructure. Sharing a result, a scenario or a Perspective can make a contribution reusable while preserving the permissions and attribution attached to it.

Building on the platform

Applications integrate through the SDK. Assistants reach the same capabilities through MCP, where each operation runs under the evidence and authority controls described on this page. A service built for a particular group, such as a lender, a college or a neighborhood organization, can combine its own interface, data connections and relationships with models and Perspectives that others maintain.

Models you write

The platform's system dynamics solver executes models of stocks, flows and the equations behind them. Stocks represent amounts such as people waiting, trained workers, usable equipment or money in a fund. Flows change those amounts; delays, lookup tables, arrays and feedback express the mechanism. Models use their declared units and time. A nonspatial model needs no invented location or calendar.

An assistant can find a suitable model in a shared library, derive a draft from a person's account or adapt an owned model. In the browser, the person can inspect its diagram, equations, assumptions and source, edit it, check it and prepare a proposal. The resulting run keeps its link to the originating draft and exact approved content. Sharing and reuse preserve authorship, permissions, evidence and limits.

Admission checks names, units, conservation and declared bounds. Fixed and adaptive integration support different time scales and locate events and rate switches. Numerical assessment compares declared refinements and independent methods under one work budget. Extreme-condition tests examine zero and declared large stock values, flow directions and bounded behavior. These checks assess the calculation and the model as written; they do not establish its relationship to the world.

A structure can be prepared for scientific review with its sources, assumptions, reference reproductions, numerical checks and intended use. An assistant prepares the review; an authorized human reviewer approves its exact structure, parameters and intended use. A changed structure, withdrawn decision or lost authority requires revalidation. An unreviewed structure returns its calculations without borrowing the standing of a reviewed solver or neighboring model.

One scenario, three kinds of model

A single scenario can combine the three kinds of model the platform holds: physical models of flood, heat, noise, air, crowds and traffic; stock-and-flow models you or your assistant write; and network science methods. Each part contributes the quantities and mechanisms relevant to the question.

Arrivals from traffic can feed a service queue. Waiting can determine exposure at a stop. A conservative transfer rule can move a declared quantity across an identified graph. An investment trajectory can change inputs to a physical calculation, whose outcome then changes the next period of the dynamics model. The experiment records both the component results and their interaction.

How models combine

Every connection declares its source, quantity, units, population or geographic coverage, clock, transformation and provenance. Data are read from the authorized retained source; material changes invalidate dependent approval. A graph connection does not create a physical rate. Models, mappings and experiments declare their effective spatial and temporal resolution; claims remain within that detail, and interpolation adds no resolution.

A one-way mapping supplies a completed result to a later model. A feedback experiment declares component state ownership, exchange times, update order, interpolation, events and stopping conditions. Long-term and event-scale models can alternate while preserving their complete continuation state, including delays, reducers and pending events. Calendar correspondence is explicit when the question requires it.

The coupled rule is checked as well as the components. Split-run agreement, refined component integrations and halved exchange intervals assess the selected outputs against declared tolerances. Failure and retry preserve completed upstream evidence and consistent component states. A partial experiment cannot appear as a completed result. Reference reproductions check component models; published hybrid comparisons test the machinery joining them. Evidence for two component models does not automatically validate their coupling.

External model results enter through documented, source-bound connections with compatible quantities and authorized access. They retain the provider, model version, permitted use and replay limits alongside their source and time support. Models without a declared interaction remain independent. The simulation reference describes the connection types and their inputs.

Bounded experiments under human control

An experiment specifies a finite set of runs or a bounded sequence, its dependencies, alternatives, observations, work limits and stopping rules. One approval covers that declared scope, including authorized inputs derived from earlier results. Each child run remains separately watchable and readable. A material revision outside the scope returns for approval.

The record links proposals, approved models, component executions, source transformations, retained products and readings. The browser brings them together without inventing a common clock for products measured at different scales. Cancellation, failure and retry preserve the distinction between completed evidence, unfinished work and a usable comparison.

Explanation, sensitivity and uncertainty

Feedback analysis identifies the loops contributing to a model's behavior and how their influence changes over time, with the dominant loop highlighted on the diagram during replay. Parameter sweeps compare declared settings. Morris screening identifies influential inputs. Saltelli designs estimate first- and total-order Sobol’ indices under stated independent distributions, with bootstrap intervals and convergence comparisons. Replicated stochastic runs preserve seeds and member identities. Comparisons retain matched samples and chance conditions across alternatives, including declared correlation and every failed member.

Numerical uncertainty, parameter uncertainty, stochastic variation and structural uncertainty remain separate channels. A summary states its population, included and excluded sources, successful and failed members and the assumptions governing its interpretation. Agreement between calculations does not erase an unreviewed structure or justify a higher evidence grade.

Comparisons can distinguish an intervention's own effect, effects on other units and its total policy effect under an explicit estimand. Distributional readings can show a total improvement alongside harm to a group. Policy-rule comparisons use declared candidates, observations, constraints and criteria; they do not imply an unrestricted optimum. A rule declares the quantities it observes, observation delays, action delays and stopping conditions. Its firings are recorded and reproduced during replay. A robustness reading reports how many members meet a stated criterion, out of how many declared members and under which distributions.

Learning from additional evidence

Value-of-information calculations compare finite choices using declared scenario weights, an observation model and losses expressed in one stated unit. They retain the expected loss before and after the specified information and the assumptions on which that difference depends.

Model fitting checks which parameters the observations can identify and separates fitting data from validation evidence. State estimation updates the inferred state under its declared observation and process model, recording observation-driven corrections separately from physical inflows and outflows. Empirical suitability remains a question for evidence, review and the intended use, with no fabricated observations or automatic scientific approval.

These capabilities support an ongoing inquiry: a person can inspect an assumption, compare another intervention, collect an observation that matters and return to the same model with a clear record of what changed.

See the public purpose · Follow the experience · Contact Robert Kirkpatrick