Audit remediation: immutable seals, real variable coupling, effective API dials, repaired CI
Executes the remediation plan from a full audit of origin/main. Six commits, each independently verifiable.
Depends on #160 (the main sync), otherwise the packaging fix here conflicts with the stale social_connectors declaration that still lives on main.
0. Pre-registration seals were not seals
Running pytest rewrote six versioned artefacts on every run — prereg_*.yaml (registered_at), datasets/ground_truth/splits.json (sealed_at) and _provenance_registry.json. A seal that re-stamps itself cannot prove that thresholds were locked before the data was seen, which is the entire claim of the pre-registered anti-leakage protocol.
Three causes, all fixed at the semantic level:
seal_splits()always wrotesealed_at = now(); it also contained a latent bug wheresealed_atwas briefly assigned the_sha256_strfunction object. It now only advances when the sealed payload changes.pre_register()wroteregistered_at = now()twice per call. It now preserves the original timestamp unless the registered content changes, and writes once.register_dataset()always re-stamped, and the registry cache was a single module-level dict, so a redirected registry leaked into the real one. The cache is now keyed by resolved path.
Tests redirect all three mutable artefacts to a temp root, and a session guard fails the suite if any sealed artefact changes (verified to fire).
1. The model was not a coupled system
Measured on the real engine: 2 of 20 possible cross-couplings, both positive, no feedback cycle, and 4 of 5 state variables inert. Perturbing cooperation, income or info_access moved no output by more than 0.0007. Polarization was 0.697 ± 0.005 for every seed, population size, dt and layer weighting — the model was a near-constant with nothing to optimise.
The coupling is now an explicit, auditable table where every term carries its mechanism (COUPLING_RATIONALE): density 10% → 30%, and it closes a cycle opinion → cooperation → info_access → opinion.
| source → target | gain | mechanism |
|---|---|---|
| opinion → cooperation | +0.40 | social alignment (pre-existing) |
| hierarchy → cooperation | +0.30 | conformity / legitimacy (new) |
| hierarchy → income | +0.40 | stratification (new; replaces a link that cancelled at its own fixed point) |
| cooperation → info_access | +0.20 | civic engagement (pre-existing) |
| income → info_access | +0.30 | digital divide (new) |
| info_access → opinion | +0.50 | selective exposure — closes the loop (new) |
Three design defects fixed: income was dead (relaxed to a flat 0.5 with no in-edges; spread 0.099 → 0.198), hierarchy was bistable but disconnected, and the network force touched only opinion (it now reaches all five dimensions).
Measured: echo-chamber gain 0.0 → 0.75 moves polarization 0.6909 → 0.7820; coupling 0.0 → 1.0 moves it 0.7249 → 0.8408; ablating any single term changes the outcome. Ablating all of them reproduces the old pathology exactly (income spread collapses back to 0.0885).
2. Two bugs found while implementing
/v1returned the same opinion trajectory three times undersocial/digital/economic. Nowseries.opinionplus a real per-layer signalmean(A_l · opinion), computed as an O(N) dot product because the layers are row-stochastic.dynamic_rewiring()refreshed only the dense copy whilestep()reads the sparse view: 90% censorship removed 720 edges from the dense view and ZERO from the one the dynamics use. Censorship and viral-hub interventions had no effect whatsoever.
3. Memory
Removed the duplicate dense (L, N, N) stack: init peak at N=2000 293 MB → 132 MB (-55%); the removed copy would have cost 2.4 GB at N=10000. The dense kernel went from a triple Python loop over (layer, agent, neighbour) to a matmul.
4. The API could not influence the model
n_agents, steps and seed do not move the result; coupling does, and it was unreachable. New POST /v1/engine/multilayer with coupling, dt (bounded to the explicit-Euler limit), layer_weights and coupling_gains as "source->target" overrides, so ablated variants and counterfactuals are expressible over HTTP. 10 contract tests.
5. The advertised type gate was broken
.github/workflows/lint.yml ran mypy --config-file mypy.ini, but that file was deleted when [tool.mypy] moved into pyproject.toml. mypy exits 2 with "Cannot find config file", so Lint & Type Check failed on every run and the "Type-check: MyPy (blocking)" badge backed nothing. It now delegates to scripts/typecheck_slice.py, and the slice grows 25 → 32 files — including multilayer_engine.py, which sat outside every gate and is exactly why the defects above survived.
6. Security, obsolete code, coverage
- bandit 48 → 41 findings, 7 MEDIUM → 0: coerced HTTP timeout (a null
llm_timeoutcould hang the simulation loop), URL scheme validation beforeurlopen,torch.load(weights_only=True)in examples, andmassive servenow binds127.0.0.1instead of0.0.0.0by default. - CfC no longer loads by default: it was disqualified by walk-forward validation, yet every engine instantiation imported torch, computed a τ matrix and logged a disclaimer to apply no correction.
DEFAULT_CONFIGhad no seed, so two identical CLI runs returned different results despite the README promising "seeded RNG everywhere". Found by a determinism test; now seed 42 with a--seedoverride.tests/test_packaging_contract.pypins the defect class that reachedmainand immediately found two live ones:metrics/py.typeddeclared as package-data but absent (type checkers ignored the package), and theadapters*glob resolving to no package.- Coverage: CLI 0% → 74%,
sentiment.py0% → 100%, total 69.02% → 70.03%;fail_under30 → 65, because a 30% floor could never detect a regression.
Verification
| gate | before | after |
|---|---|---|
ruff check . | clean | clean |
black --check . | clean | clean |
mypy (blocking slice) | CI broken, 25 files | ✅ 32 files |
pytest | 883 | 918, 0 failures |
| coverage | 69.02% (floor 30) | 70.03% (floor 65) |
bandit | 48 (7 MEDIUM) | 41 (0 MEDIUM) |
working tree after pytest | 6 sealed files rewritten | clean |
⚠️ Breaking changes
- Default dynamics change. Existing calibration artefacts (
configs/calibrated/, pre-registration seals) describe the previous potential and must be re-derived before being quoted as validation evidence. This is the honest consequence of fixing the coupling, not an oversight. /v1multilayer series shape changed ({opinion, layer_signal}), served by a dedicated endpoint.
🤖 Generated with Claude Code
Summary by cubic
Executes the audit remediation plan: fixes seals that re-stamped themselves, replaces the near-constant engine with a genuinely coupled system, exposes the dials that actually matter over HTTP, makes the layers memory-efficient, and repairs the inert CI type gate plus a Docker image that could not be built.
Breaking changes: default engine dynamics change, so calibration artefacts (configs/calibrated/, pre-registration seals) must be re-derived before being quoted as validation evidence; the /v1 multilayer series shape changed and is now served by a dedicated endpoint; and the economic layer now has a bounded hub degree, so a given seed yields a different network than before.
Engine and seals
- Seals re-stamped
registered_at/sealed_aton every test run; they now only advance when the sealed payload changes, and a session guard fails the suite if any sealed artefact changes. - The model had 2 of 20 possible cross-couplings, no feedback cycle, and 4 of 5 state variables inert; coupling is now an explicit auditable table that closes a
opinion → cooperation → info_access → opinioncycle. incomewas dead (spread 0.099 → 0.198); the network force now reaches all five dimensions.dynamic_rewiring()modified the dense layer copy whilestep()reads the sparse view, so censorship had no effect; both views now rebuild together./v1returned the same opinion trajectory three times; series now returnsopinionplus a real per-layermean(A_l · opinion)signal.- Layers and the hub core were O(N²): layers now build CSR natively (resident 1536 MB → 1.2 MB at N=8000) and hub degree is bounded (init peak 8.4 GB → 31 MB at N=16000), with bit-identical parity against the dense path.
- Coverage: CLI 0% → 74%,
sentiment.py→ 100%,ground_truth/_generate.py0% → 50% (the sealed-data generator), total 70.45% withfail_underraised 30 → 65; the IPF fitter no longer divides by zero.
API, CI, and Docker
- New
POST /v1/engine/multilayerexposescoupling,dt,layer_weights, andcoupling_gainsoverrides; the previously exposedn_agents,steps, andseeddo not move the result. - Contract tests pin the public router surface: 401 on missing/wrong keys, path-traversal rejection, fail-closed 503 when LLM mode lacks a provider key, response-shape validation, and input bounds (forecast 29% → 87%, benchmarks 18% → 62%).
- All nine workflows filtered PRs to
[main, master], so PRs into other long-lived branches got no checks; they now run on any target branch. lint.ymlranmypy --config-file mypy.iniagainst a deleted file; it now delegates toscripts/typecheck_slice.py, which graduated from hand-picked files to the full clean scope (0 errors after fixing 26 type errors, notablyfloat()overCalibratedValue), and installs lint tools from the pinneddevdependencies.- The Docker image could not be built at all:
Dockerfilecopiednginx.confandsupervisord.conf, which did not exist. Both are now included, written for the non-root container user, uvicorn binds0.0.0.0so the published :8000 port is reachable, and the torch index defaults to CPU instead of pulling ~2.6 GB of nvidia-* wheels. - The gitleaks secret scan checked out a shallow history, so it scanned ~0 bytes; it now fetches full history.
DEFAULT_CONFIGhad no seed, so identical CLI runs returned different results; defaults to seed 42 now, and the CLI forecast command applies per-event-type temporal defaults.- Bandit 48 → 41 findings with 7 MEDIUM → 0: HTTP timeout coercion, URL scheme validation,
torch.load(weights_only=True), andmassive servebinds127.0.0.1by default. - The legacy
api.pymodule has no frontend consumers; it now emits aDeprecationWarning, theapi-legacyMakefile target and theinstall.shfallback warn loudly, and the runbook no longer claims the React app depends on it.