Audit remediation: immutable seals, real variable coupling, effective API dials, repaired CI

AD
21d ago
+3793-251

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 wrote sealed_at = now(); it also contained a latent bug where sealed_at was briefly assigned the _sha256_str function object. It now only advances when the sealed payload changes.
  • pre_register() wrote registered_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 → targetgainmechanism
opinion → cooperation+0.40social alignment (pre-existing)
hierarchy → cooperation+0.30conformity / legitimacy (new)
hierarchy → income+0.40stratification (new; replaces a link that cancelled at its own fixed point)
cooperation → info_access+0.20civic engagement (pre-existing)
income → info_access+0.30digital divide (new)
info_access → opinion+0.50selective 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

  • /v1 returned the same opinion trajectory three times under social/digital/economic. Now series.opinion plus a real per-layer signal mean(A_l · opinion), computed as an O(N) dot product because the layers are row-stochastic.
  • dynamic_rewiring() refreshed only the dense copy while step() 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_timeout could hang the simulation loop), URL scheme validation before urlopen, torch.load(weights_only=True) in examples, and massive serve now binds 127.0.0.1 instead of 0.0.0.0 by 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_CONFIG had 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 --seed override.
  • tests/test_packaging_contract.py pins the defect class that reached main and immediately found two live ones: metrics/py.typed declared as package-data but absent (type checkers ignored the package), and the adapters* glob resolving to no package.
  • Coverage: CLI 0% → 74%, sentiment.py 0% → 100%, total 69.02% → 70.03%; fail_under 30 → 65, because a 30% floor could never detect a regression.

Verification

gatebeforeafter
ruff check .cleanclean
black --check .cleanclean
mypy (blocking slice)CI broken, 25 files✅ 32 files
pytest883918, 0 failures
coverage69.02% (floor 30)70.03% (floor 65)
bandit48 (7 MEDIUM)41 (0 MEDIUM)
working tree after pytest6 sealed files rewrittenclean

⚠️ Breaking changes

  1. 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.
  2. /v1 multilayer 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_at on 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 → opinion cycle.
  • income was dead (spread 0.099 → 0.198); the network force now reaches all five dimensions.
  • dynamic_rewiring() modified the dense layer copy while step() reads the sparse view, so censorship had no effect; both views now rebuild together.
  • /v1 returned the same opinion trajectory three times; series now returns opinion plus a real per-layer mean(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.py 0% → 50% (the sealed-data generator), total 70.45% with fail_under raised 30 → 65; the IPF fitter no longer divides by zero.

API, CI, and Docker

  • New POST /v1/engine/multilayer exposes coupling, dt, layer_weights, and coupling_gains overrides; the previously exposed n_agents, steps, and seed do 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.yml ran mypy --config-file mypy.ini against a deleted file; it now delegates to scripts/typecheck_slice.py, which graduated from hand-picked files to the full clean scope (0 errors after fixing 26 type errors, notably float() over CalibratedValue), and installs lint tools from the pinned dev dependencies.
  • The Docker image could not be built at all: Dockerfile copied nginx.conf and supervisord.conf, which did not exist. Both are now included, written for the non-root container user, uvicorn binds 0.0.0.0 so 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_CONFIG had 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), and massive serve binds 127.0.0.1 by default.
  • The legacy api.py module has no frontend consumers; it now emits a DeprecationWarning, the api-legacy Makefile target and the install.sh fallback warn loudly, and the runbook no longer claims the React app depends on it.