This repository hosts figures, notebooks, reproducibility scripts, and PDFs for submissions related to the mathematical theory behind the Civic Interconnect project.
On Windows (MiKTeX):
- Download from https://miktex.org/download.
- Suggested options during installation:
- Install for current user only
- Leave paper size at A4 (default is fine)
- Install missing packages on the fly = Yes
- Add MiKTeX to PATH = Yes
On macOS / Linux:
- Install TeX Live (or MacTeX on macOS) from your package manager or the TeX Users Group site.
Ensure latexmk is available (MiKTeX and TeX Live usually include it).
Build all three papers:
.\build.ps1Or build just one paper:
cd paper02
latexmk -pdf -bibtex -interaction=nonstopmode -auxdir=build -outdir=build 00P2_cep_semantics.tex
cd ..VS Code users: Press Ctrl+Shift+B (or Cmd+Shift+B on Mac) for quick build.
See draft papers at:
- CAE - civic accountable entities (what kinds of things exist)
- CEP - entity, relationship, exchange, envelope (how hings relate and transform, morphisms)
- CEE - vertical stacks and spines; how claims are supported and explained (evidence, 2-morphisms)
| Paper | Layer | Framework | Role |
|---|---|---|---|
| P1 (CAE) | Ontology | Ontology/KR | Accountable entities and kinds |
| P2 (CEP) | Exchange | Category theory | Entity, relationship, exchange, envelope |
| P3 (CEE) | Evidence | Bicategory theory | Observations, provenance, explanations |
The stack builds upward:
- P1 provides sorts. There are Actors, Sites/Assets, Instruments, Events, Jurisdictions, Observations. They are disjoint. Here's what makes each kind what it is.
- P2 provides morphisms. Here's what it means for value to flow from Actor A to Actor B under Instrument I, recorded as Event E. Here's how such exchanges compose. Here's what structure is preserved.
- P3 provides 2-morphisms. Here's how one interpretation of an exchange relates to another interpretation. Here's how an explanation justifies a claim. Here's how different models reaching different conclusions from the same data can be compared.
Each accountable entity is assigned exactly one kind.
- Actors (A) - capable of bearing rights and obligations.
- Sites/Assets (S) - physical or operational entities acted upon
- Instruments (I) - enduring constructs that create or constrain obligations.
- Events/Records (E) - time-indexed assertions that something occurred.
- Jurisdictions (J) - scope authority and applicability.
- Observations (O) - measurements and indicators describing state, outcomes, or performance over time.
An exchange is not an entity; it is a constrained subgraph pattern. A record or dataset is admissible to CEP if and only if it contains, or can be mapped to, a subgraph that includes:
- At least one Instrument (I) that creates, modifies, or constrains obligations
- At least one Event (E) that occurs under that Instrument
- At least one Actor (A) that is party to the Instrument or involved in the Event
Every exchange event that conveys value must carry a Value Expression, either monetary or in-kind, with explicit units and provenance.
CEE adds transparency to civic decisions by requiring structured explanations for why entities are highlighted, selected, or prioritized. Rather than treating decisions as black boxes, CEE attaches observations (what was measured), evidence (what data supports the claim), and attributions (which model or actor made the decision) to specific entities and relationships. This enables comparing how different models reach different conclusions from the same data, tracking decision provenance over time, and surfacing the reasoning behind civic processes, from loan approvals, to procurement awards, to resource allocation. CEE does not make value judgments; it surfaces information so stakeholders can make informed decisions.
This repository does not attempt to prescribe policy outcomes, evaluate the desirability of specific decisions, assert causal claims between civic actions and outcomes, or provide a complete implementation of civic data systems. It does not define sector-specific metrics, mandate particular analytical models, or privilege any single explanatory framework. The mathematical structures developed here are intended to make accountability, exchange, and evidence representable and comparable, not to determine what conclusions should be drawn from them. Normative judgment, policy choice, and domain-specific evaluation are deliberately left to downstream actors, institutions, and analytic layers built on the CAE/CEP/CEE framework.
This repository documents decisions using Civic Interconnect Contextual Evidence & Explanations (CEE) annotation standard defined in: Civic Interconnect ANNOTATIONS.md.
Civic Interconnect implements the CAE/CEP/CEE framework for civic accountability tracking.
For implementation, adapters, and examples, see the Civic Interconnect Repository.
This work is under active development.
Licensed under CC BY 4.0.
See CITATION.cff for citation details.