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.
• 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.

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.
• 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¶

• 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.
• 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.

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.
• 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.

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.