Maintainer Notes¶

docs/AI records durable implementation details: contracts, design rationale, cache and artifact semantics, resolved failure modes, and maintenance guidance. The notes are grouped by the part of the repository that owns the behavior.

This index and the linked notes were audited against the working tree on 2026-08-10. Treat dated incident and tuning notes as historical evidence; the current contract is stated explicitly in each note.

Architecture¶

• Public Markov state — state bits shared by environments, learned models, exact graphs, and shielding.
• Safety abstractions — the per-agent safety projection used by runtime cost accounting and graph labelling.

Environments¶

• Retired benchmarks, August 2026 — evidence, restoration point, rl-engine handoff, and artifact policy.
• Scalable opponent-shielding candidates — ranked custom n-agent benchmarks and anti-confounding requirements.
• Scaling beyond two agents (Oct 2026) — Congestion n = 3/4 outcomes, where cost grows, and graph and OM sizes of n-agent candidates
• Hidden episode cap — inferred episode limits, truncation/bootstrap rules, and wrapper bookkeeping.
• Ice Duel safe start — movement, shove, terminal-edge, and safe-start behavior.
• Pursuit safety — the global goal-region failure label.

Joint Graphs¶

• Architecture — graph types, edge fields, exact legality, augmentation, and focal-MDP induction.
• Legal dynamics size — exact counts, upper bounds, and export verification.
• Time-augmented state width — why exact builders must preserve the public Markov state width.
• Pursuit exact-graph memory — graph-size guardrails for two- and three-agent Pursuit.
• Gathering freeze timing — exact reachability and cache invalidation for frozen-agent semantics.

World Model¶

• Checkpoint loader — inferring hidden width and safely loading older world_model.pt files.
• Coverage-aware pretraining — balanced live-policy collection and the Ice Duel calibration audit.
• Masked categorical successor kernel — learning Gamma(s'|s,a) directly over legal successors, why there is no sink logit, exact count aggregation, and successor-conditioned rewards.

Opponent Model¶

• Autoregressive joint OM — exact chain-rule likelihoods, compatibility enumeration, checkpoint migration, and the remaining joint-action scaling boundary.
• Joint-graph integration — legality and the env_transition_graph.pkl handoff.
• Training semantics — level 0, imagined root-state samples, and progress accounting.
• Runtime fast path — cached legality masks in imagined rollouts.
• Level-0 holdout metrics — train and validation split behavior.
• Closest-retained-level gap — the A2 opponent gap at the shield's floor, its training-time logging flag, and the offline measurement on frozen campaign policies.
• Pursuit 3-agent memory — historical adapter OOM repair and the current stochastic materialization limit.
• Private-reward inference ablation — heterogeneous matrix payoffs, pre-training-only inverse QRE, identification, and matched export/evaluation contracts.

Shielding¶

• Interactive field guide — an offline teaching website covering winning regions, carried budgets, interval VI, learned allocations, and opponent floors, with explicit toy-model boundaries.
• Teaching-site mathematical audit — checks against Edwin's paper, the AAMAS tutorial and the OmSh manuscript; numerical boundary fixes and guarantee assumptions.
• Updated teaching theory — simultaneous-move randomisation, permissiveness, count-centred coverage and the distinction between risk-dominance theorems and empirical audits.
• Architecture — sound value iteration, immutable bundles, runtime decisions, telemetry, and patience.
• Budget-augmented shielding — the robust replacement-shield state and successor-budget rule.
• Parameterized actions — pairwise mixed primitive actions, learned successor budgets, hybrid PPO, and the 2×2 ablation contract.
• Coordinated multi-agent OmSh — independent role-conditioned IOPs, budgets, posteriors, and joint action resolution.
• Safety horizon semantics — the time-free infinite-horizon default, finite-horizon variants, reset semantics, and reporting contract.
• Notebook integration — learned shield artifacts, cache identity, and environment factories.
• True-policy exact shield — the exact transition baseline and live policy refresh.
• Exact anytime arbitrary-opponent certificate — theorem-facing outer kernel, independent validation, runtime contract, and environment routing.
• Anytime ambiguity sets — count-centred confidence sequences, two-ended transport for the robust Bellman step, radius marginalisation, and why convergence changes meaning under a radius.
• Level-floor patience — sustained-evidence semantics for monotone opponent-level raises.
• Opponent-uncertainty modes — the default monotone floor and credible/all-level/Bayesian ablations.
• Posterior-credible floor — credible suffix selection, time-uniform error allocation, assumptions, and telemetry.
• Repeated matrix feasibility — environment repair pattern and initial-budget feasibility.
• Congestion infeasibility — detour semantics and cache implications.
• Pursuit 3-agent infeasibility — reset feasibility under robust eventual-risk bounds.
• Pursuit stochastic dynamics — exact slip support, cache invalidation, and the required artifact rebuild.
• Pursuit slip-rate radii — per-row world-model radii from a time-uniform slip-rate box ("known rules, unknown rates"), with the padded-certificate demand and the opponent slack left at each floor.

Reinforcement Learning¶

• JAX IPPO migration — shared trainer interfaces, cost handling, and notebook integration.
• Discrete ICPO port — the repo-native constrained-policy implementation and compatibility decisions.
• Frozen final-policy safety — restorable checkpoints, live survival estimates, and exact stationary-policy reachability.
• Final-policy campaign report — all-algorithm frozen-policy aggregation, worst-seed safety gates, and exact baseline reachability joins.

Notebooks¶

• Marimo experiments — CLI overrides, execution control, timing sidecars, and artifact dependencies.
• Project-root working directory — stable paths in interactive and script execution.
• Environment discovery — shared notebook metadata and export-root rules.
• Utility layout — importable helpers versus runnable notebook entry points.
• Ablation notebooks — WM/OM ablation conditions and export layout.
• Hyperparameters, April 2026 — rationale for current environment-specific defaults.
• Diagram notebooks — common graph slicing and rendering infrastructure.
• IOP diagrams — reasoning-level diagram behavior.
• IOP state layout — layout modes and transition previews.
• Timings report — timing and allocated-hardware reporting.

Experiments and Presentation¶

• Cluster submission scripts — Slurm/PBS dependency graphs, routing, validation, and deployment controls.
• Export layout — histories, figures, and legend outputs.
• Episodic reporting — canonical episode rows and paper/report graphs.
• Visualisation styling — local plotting conventions and maintenance boundaries.
• Clean timing run — exclusive amd48 nodes, one pinned core, fresh exports root; why the shared-node amd96 attempt was dropped.
• Paper data audit (15 Oct 2026) — how every paper number was checked against the archive, the fixes, and what rests on documented analyses only.
• Follow-ups F1, F2, F4 — post-AAMAS level-0 and exact-kernel shield ablations and Pursuit at 10 seeds: design, predeclared rules, verdicts.
• Reward-safety frontier study (Oct 2026) — budget and cost-limit sweep, exact-kernel opponent-model control, and novelty-driven collection for the certified shield: designs and predeclared rules.
• Successor world-model campaign — Stage 2A: which launcher runs which stage, per-stage memory, and how the comparison separates the world-model effect from a reproduction check.
• World-model variant study — the Stage 1 kernel-estimator comparison, its shared fitting protocol, and the predeclared adoption gate.
• Certified ambiguity study — the Stage 2B certificate-width and feasibility sweep, its stream-prefix counting protocol, and why the oracle stays diagnostic.
• Reviewer diagnostics — always-on reports, optional bounded traces, artifact layout, and interpretation rules.
• Evaluation and optimisation — staged OmSh baseline comparisons, variant prioritisation, and review assumptions.

Operations¶

• Documentation — Zensical layout, navigation, validation, and the user/maintainer content split.
• Test runtime — component ownership, changed-file selection, and fast/slow policy.
• Logging — the shared Loguru-backed engine and file locking behavior.
• Canonical interface cleanup — removed aliases, accepted artifact schemas, and required rebuilds.
• Repository cleanup, Oct 2026 — lint, dead code, the shared stage game, ruff format; how each pass was verified and what was left alone

Maintenance Rules¶

• Update an existing note when a contract changes; do not leave the old claim in place as if it were still current.
• Put a new note in the narrowest owning subfolder and add it to this index.
• Record the cache/version consequence whenever state, graph, safety, or shield semantics change.
• Keep user instructions in the main Zensical pages under docs/; link here only when implementation depth is useful.
• Validate documentation-only changes with uv run zensical build --strict and uv run python scripts/run_tests.py changed.