Source snapshot · 20 October 2026
+ +Explore the game's architecture through readable UML views, source-linked reports and a reproducible inventory. This atlas describes [Civ13/Civ13 at 5bf351248de6](https://github.com/Civ13/Civ13/tree/5bf351248de6050876fe5b53f91209a970cc5668), not the state of a deployed server or unmerged changes. + + + +[Read the audit]({{ '/architecture/audit/' | relative_url }}) · [Browse the diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Validation and limits]({{ '/architecture/validation/' | relative_url }}) + +
+
+Open the overview image for a full-size, zoomable SVG.
+
+## Downloads
+
+- [UML atlas PDF · 19 pages · 1.4 MB]({{ '/public/architecture/2026-10-20/Civ13-architecture-UML-atlas.pdf' | relative_url }})
+- [Complete evidence bundle · ZIP · 11.2 MB]({{ '/public/architecture/2026-10-20/Civ13-architecture-audit-evidence.zip' | relative_url }})
+
+The bundle contains editable PlantUML/Mermaid sources, rendered diagrams, reports, machine-readable inventories and reproduction tools. Large call-site tables are downloadable rather than rendered into this page.
+
+## Explore by subject
+
+- [Runtime and gameplay]({{ '/architecture/runtime/' | relative_url }}): startup, scheduler ownership, rounds, movement, combat, crafting, research and AI.
+- [Persistence and services]({{ '/architecture/persistence/' | relative_url }}): save/load ownership, restart recovery, Help, file spools and external boundaries.
+- [Diagram gallery]({{ '/architecture/diagrams/' | relative_url }}): 18 UML views plus two explicitly labeled dependency/call-candidate graphs.
+- [Source-group coverage]({{ '/architecture/coverage/' | relative_url }}): 46 source groups and their inventory counts.
+
+## What was inventoried?
+
+- **1,462** tracked DM files.
+- **1,257** files in the root environment's textual include closure, totaling **383,278** lines.
+- **93** registered research nodes and **99** prerequisite edges.
+- **215** source links checked for existing files and valid line ranges.
+
+These are file and lexical inventory counts, not compiler-certified symbol totals or runtime coverage percentages. Included, activated and deployed are different claims.
+
+## Main review targets
+
+1. Different restart paths use different recovery contracts.
+2. Scheduler comments and included controller infrastructure do not always establish actual ownership or activation.
+3. Custom persistence couples domain state, transient-field exclusions and derived-state reconstruction.
+4. Click, Topic, UI, callbacks and service spools have distinct entry-point and authority boundaries.
+
+These are architectural review concerns, not asserted runtime defects or a security certification. See the [full audit]({{ '/architecture/audit/' | relative_url }}) for evidence and recommended next steps.
diff --git a/architecture/audit.md b/architecture/audit.md
new file mode 100644
index 0000000..3ce9b63
--- /dev/null
+++ b/architecture/audit.md
@@ -0,0 +1,113 @@
+---
+layout: default
+title: "Architecture audit"
+permalink: /architecture/audit/
+description: "Source-pinned Civ13 architecture, UML diagrams, evidence boundaries and downloadable audit artifacts."
+image:
+ path: /public/img/architecture-overview.png
+ width: 1922
+ height: 573
+ alt: Civ13 architecture component overview
+---
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
+
+# Civ13 architecture audit and UML atlas
+
+Audit date: 2026-10-20. Source: [Civ13/Civ13 master at 5bf351248de6050876fe5b53f91209a970cc5668](https://github.com/Civ13/Civ13/tree/5bf351248de6050876fe5b53f91209a970cc5668). This is an immutable source snapshot, not a report of the deployed server or unmerged pull requests.
+
+## Executive result
+
+Civ13 is a BYOND/DM game with a large subtype/content tree, global registries and singleton controllers, a legacy process scheduler, independent yielded/deferred activities, map-specific round policy, and custom durable persistence. Its architecture cannot be understood as one linear main loop. Native BYOND events, virtual proc overrides, hook enumeration, queued callbacks, browser Topic messages, file spools and world reloads all add entry points.
+
+The atlas covers the entire tracked DM file inventory and the literal include closure of civ13.dme. It provides focused UML views of the important lifecycle and subsystem interactions, plus searchable source-linked declarations, inheritance candidates, call sites, control sites and unresolved/dynamic sites. It does **not** claim that all possible executable runtime paths have been enumerated. Loops, recursion, dynamic dispatch, mutable types/data, timing and external input make that set unbounded; a lexical scan cannot prove path feasibility or reachability.
+
+### Findings that matter
+
+1. **Scheduler ownership needs an executable source of truth.** Legacy /process scheduling coexists with included MC/timer infrastructure and independent movement/spawn loops. Comments suggesting subsystem ownership do not establish active routing. Keep lifecycle diagrams tied to actual startup and registration, not only file names. See [runtime audit]({{ '/architecture/runtime/' | relative_url }}).
+2. **Restart contracts differ.** Owned transactional restart recovery and scheduled maintenance save/reboot do not have the same completion/intent contract. This is a design consistency review target, not a demonstrated data-loss defect. See [persistence audit]({{ '/architecture/persistence/' | relative_url }}).
+3. **Persistence crosses nearly every domain.** A custom variable serializer, explicit runtime-field exclusions, durable graph schemas and identity restoration must evolve together. A new transient pointer/clock or cross-level relationship can invalidate save assumptions. Treat schema/ownership review as a feature gate, not an optional follow-up.
+4. **Entry-point and authority boundaries are distributed.** Click, native client/world callbacks, NanoUI, direct Topic handlers, admin verbs, Discord spools and Help worker exchanges have different gates. The presence of one UI or client gate does not prove that every alternate entry route is protected. No security vulnerability is asserted by this architecture audit.
+5. **Derived state has distinct reconstruction phases.** Lighting corners/overlays, processing registries, runtime reservations and restored-round daylight are not interchangeable with ordinary saved gameplay state. Startup and restoration should have separately testable invariants.
+6. **Names and comments can overstate behavior.** The preferencesSQLite directory uses delimiter-file storage on the audited path. Research comments describe optional prototype shortcuts while executable research completion requires the prototype gate. Distinguish documentation debt from proven functional bugs.
+7. **Included, activated and deployed are different claims.** Experimental gameplay bridge and immutable_capture sources are outside the main include closure. Human sub-tile movement is included but defaults disabled. Bot-service deployment is separately blocked by repository guidance. This audit changes none of those states.
+
+## Coverage and evidence strength
+
+| Scope | Result |
+|---|---:|
+| Tracked DM files inventoried | 1,462 |
+| Tracked DM source lines | 415,124 |
+| DM files in textual include closure | 1,257 |
+| Source lines in that closure | 383,278 |
+| Included proc declaration candidates | 14,081 |
+| Included type declaration/reopening candidates | 13,131 |
+| Tracked support files inventoried (selected source/map/UI/workflow extensions) | 660 |
+| Python AST function/class declarations | 2,036 |
+| Python parse errors | 0 |
+
+These are inventory counts, not compiler-certified symbol totals or a percentage of runtime behavior tested. Included types can be reopened; proc declarations can be conditionally compiled or macro-generated. Explicit parent_type overrides are recorded separately from path-default ancestry. All tracked DM files are scanned, including excluded tests and experimental sources; use in_include_union to filter production candidates.
+
+The include closure is a **conditional union**: literal includes are followed without evaluating preprocessor conditions. No claim is made that every union member executes, or even that every union member is compiled in every configuration. The default map include is maps/nomads/nomads.dmm; other map content and runtime configuration can change reachability. Source path and SHA-256 are recorded per file.
+
+### Evidence levels
+
+- **File accounting:** complete for Git-tracked .dm files at the pin; repeatable hashing and literal include reachability.
+- **Lexical inventory:** conservative source navigation aids, not a DM compiler AST. Proc/type recognition uses path and indentation heuristics. Macro expansion, braces/multiline edge cases and quoted interpolation can escape symbol recognition.
+- **Call candidates:** call-sites.csv records spellings and receivers; call-target-name-index.json lists same-name declaration candidates. Joining them is not proof of an edge. Native builtins, macros, inherited dispatch and dynamic receivers remain unresolved.
+- **Control sites:** conditions, loops, yields and returns are indexed. lexical-order-edges.csv contains consecutive source-statement navigation edges only. It is deliberately **not** labeled an executable CFG.
+- **Manual diagrams:** selected source-traced architecture abstractions with direct supporting links in reports. They omit incidental branches for readability; their notes identify the abstraction boundary.
+- **Runtime evidence:** none newly generated. No DreamDaemon, game client, live save/load, deployed service, external model or network bridge was exercised. No source edits, commits, PRs, feature activation or deployment occurred.
+
+## Read the atlas
+
+Start with the rendered overview and core type diagram in diagrams/. Then follow runtime/report.md for scheduler, startup, movement/combat, crafting/research and AI; persistence-services/report.md for save/load/restart and external services. Source diagrams are editable PlantUML (.puml) and Mermaid (.mmd). Graphviz (.dot) is used only for explicitly labeled lexical call-candidate views.
+
+[Diagram index]({{ '/architecture/diagrams/' | relative_url }}) lists the rendered outputs and source files. SVG is zoomable; PNG is convenient for previews. The PDF atlas collects the rendered diagrams with captions.
+
+### Additional source-traced boundaries
+
+- [atom.Click and mob.ClickOn](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/_onclick/click.dm#L7): native entry forwards through usr, then target/click-clock/modifier gates and type-specific behavior. Numerous subtype overrides and early exits prevent a single universal attack path. The input sequence is a conceptual dispatch skeleton, not a statement-order proof.
+- [client.Topic](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/client/client_procs.dm#L23): current usr/mob guard precedes routing. Direct handlers still own their own authorization and validation.
+- [NanoUI Topic](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/nano/_nanoui.dm#L494): updates status, requires interactive status and matching user, calls src_object.Topic and then updates associated UIs. [Topic-state policies](https://github.com/Civ13/Civ13/tree/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/nano/interaction) encode different physical/admin/inventory/remote contexts.
+- [Lighting construction](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/lighting/lighting_system.dm#L99): first constructs shared corners with deferred activity, then ordinary and compatibility overlays, activates fresh/existing corners, and releases readiness flags. Exceptions clear readiness and rethrow. Restored rounds use [apply_restored_lighting](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/lighting/lighting_system.dm#L138), not an assumption that fresh-round setup ran.
+- [Dynamic hooks](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/hooks.dm#L50): text2path + typesof + call builds runtime dispatch from a hook name. A name-only call graph cannot recover all these edges without language/type information.
+
+## Machine-readable inventory
+
+- files.csv: all tracked DM files, include-union membership, line/byte counts, SHA-256, source permalink.
+- includes.csv: literal include edges, location and existence checks.
+- declarations.csv: proc and type declaration candidates, reopenings and exact source anchors.
+- inheritance.csv: path-default ancestry candidates plus explicit parent_type overrides. Resolve overrides before using as a final type tree.
+- call-sites.csv and call-target-name-index.json: call spellings, receiver text, source-proc association and possible same-name declarations.
+- control-sites.csv: indexed control/yield statements.
+- statements.csv and lexical-order-edges.csv: source-order navigation within recognized procs, not executable flow.
+- dynamic-unresolved.csv: construction, reflection, hooks/callbacks, spawn/sleep, macro and opaque interpolation markers. A marker can be duplicated for different reasons; totals are sites/markers, not unique defects.
+- preprocessor.csv: directives requiring a real preprocessing pass for exact compilation configuration.
+- subsystem-coverage.csv: 46 source groups and their inventory counts.
+- support-files.csv: selected non-DM source/UI/map/workflow inventory; Python AST declarations and imports are separate tables. This is not an AST/control-flow audit of every JavaScript, shell, PowerShell or map file.
+- coverage.json: machine-readable pin, totals and limitations; check-results.txt: executed accounting/anchor checks.
+
+## Recommended next engineering steps
+
+1. Adopt the inventory as a baseline, then obtain a compiler-backed, configuration-specific DM symbol/type graph. Add explicit engine entry-point roots, parent_type resolution, macro expansion and virtual dispatch sets; do not relabel lexical edges as precise calls.
+2. Make an entry-point matrix for native callbacks, verbs, Topic handlers, timers, hooks and file spools, with authority/lifetime requirements and tests per route.
+3. Document one scheduler ownership model and verify each active worker's startup, cancellation, budget and teardown paths. Remove misleading subsystem comments only after behavior is confirmed.
+4. Review restart/save contracts together, then add cross-path tests of completed-generation selection and failure holds before consolidating code.
+5. Require explicit persistence decisions for new fields and schema changes, including restored references, transient clocks, resource ownership and derived registries.
+6. For each high-risk sequence, add bounded integration/mutation tests plus real-client checks where rendering, movement timing or dispatch depends on a connected client. Existing fixture success is not blanket server acceptance.
+
+No broad refactor is recommended solely on this static audit. First improve contracts and evidence at the boundaries above, then use narrowly scoped changes with regression coverage.
+
+## Reproduce
+
+Use a clean checkout of the exact pin. Run tools/build_inventory.py with the checkout and inventory output directory, then tools/summarize_inventory.py and tools/check_inventory.py. The scripts use Python standard library and do not execute repository code.
+
+Example: python tools/build_inventory.py SOURCE_ROOT OUTPUT_ROOT/inventory
+
+To explore a proc name: python tools/query_graph.py inventory create_lighting output.dot 45, then dot -Tsvg output.dot -o output.svg. The graph explicitly labels candidate edges and reports truncation. The default node cap is 80; changing it does not improve semantic precision.
+
+Diagram render versions and verification results are recorded in VALIDATION.md. Read source reports for the evidence behind each manually drawn interaction. All repository source remains unmodified.
+
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
diff --git a/architecture/coverage.md b/architecture/coverage.md
new file mode 100644
index 0000000..5b509ac
--- /dev/null
+++ b/architecture/coverage.md
@@ -0,0 +1,69 @@
+---
+layout: default
+title: "Source coverage"
+permalink: /architecture/coverage/
+description: "Source-pinned Civ13 architecture, UML diagrams, evidence boundaries and downloadable audit artifacts."
+image:
+ path: /public/img/architecture-overview.png
+ width: 1922
+ height: 573
+ alt: Civ13 architecture component overview
+---
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
+
+# Source-group coverage
+
+Counts are lexical include-union inventory, not proven runtime coverage.
+
+| Source group | Files | Lines | Proc candidates | Type declarations | Call sites |
+|---|---:|---:|---:|---:|---:|
+| code/__defines | 41 | 1966 | 15 | 0 | 43 |
+| code/_globalvars | 1 | 25 | 0 | 0 | 18 |
+| code/_helpers | 30 | 5970 | 350 | 9 | 1255 |
+| code/_onclick | 15 | 3702 | 244 | 94 | 714 |
+| code/controllers | 6 | 1675 | 51 | 5 | 187 |
+| code/datums | 26 | 3168 | 151 | 39 | 687 |
+| code/game/area | 2 | 1757 | 11 | 363 | 131 |
+| code/game/atoms.dm | 1 | 606 | 39 | 1 | 233 |
+| code/game/atoms_movable.dm | 1 | 318 | 20 | 2 | 81 |
+| code/game/base_turf.dm | 1 | 14 | 2 | 0 | 2 |
+| code/game/core.dm | 1 | 41 | 1 | 0 | 11 |
+| code/game/dna | 2 | 459 | 33 | 1 | 127 |
+| code/game/gameticker.dm | 1 | 346 | 8 | 1 | 68 |
+| code/game/jobs | 2 | 1015 | 24 | 2 | 237 |
+| code/game/lobby_music_player.dm | 1 | 53 | 4 | 1 | 14 |
+| code/game/mob | 172 | 44254 | 1703 | 630 | 12891 |
+| code/game/objects | 373 | 94620 | 4123 | 3407 | 25427 |
+| code/game/sound.dm | 1 | 657 | 4 | 0 | 223 |
+| code/game/turfs | 21 | 6818 | 204 | 561 | 1712 |
+| code/js | 1 | 37 | 0 | 0 | 0 |
+| code/modules/1713 | 238 | 135131 | 3744 | 5578 | 49598 |
+| code/modules/admin | 54 | 10568 | 299 | 30 | 2998 |
+| code/modules/chat | 1 | 128 | 7 | 2 | 31 |
+| code/modules/client | 18 | 2687 | 136 | 37 | 658 |
+| code/modules/collectibles | 3 | 1770 | 38 | 111 | 266 |
+| code/modules/dmm_suite | 2 | 304 | 9 | 2 | 81 |
+| code/modules/error_handler | 4 | 353 | 14 | 4 | 67 |
+| code/modules/flufftext | 2 | 106 | 6 | 0 | 40 |
+| code/modules/lighting | 9 | 1130 | 63 | 6 | 184 |
+| code/modules/magic | 15 | 7686 | 260 | 278 | 1878 |
+| code/modules/materials | 2 | 2353 | 79 | 170 | 180 |
+| code/modules/multiz | 7 | 1087 | 67 | 42 | 279 |
+| code/modules/nano | 23 | 1611 | 116 | 14 | 427 |
+| code/modules/organs | 15 | 3642 | 190 | 69 | 855 |
+| code/modules/persistence | 14 | 2896 | 173 | 26 | 1408 |
+| code/modules/projectiles | 18 | 6968 | 220 | 321 | 1572 |
+| code/modules/reagents | 40 | 17735 | 872 | 1111 | 4125 |
+| code/modules/research_tree | 7 | 3104 | 63 | 6 | 682 |
+| code/modules/statpanel | 1 | 180 | 6 | 1 | 69 |
+| code/modules/submarine | 12 | 6282 | 220 | 94 | 1135 |
+| code/modules/surgery | 12 | 1787 | 128 | 39 | 649 |
+| code/modules/webhooks | 1 | 49 | 11 | 0 | 21 |
+| code/modules/xgm | 2 | 387 | 25 | 3 | 55 |
+| code/processes | 43 | 4557 | 305 | 51 | 1019 |
+| code/root | 14 | 3103 | 43 | 8 | 534 |
+| interface | 1 | 173 | 0 | 12 | 3 |
+
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
diff --git a/architecture/diagrams.md b/architecture/diagrams.md
new file mode 100644
index 0000000..caece14
--- /dev/null
+++ b/architecture/diagrams.md
@@ -0,0 +1,145 @@
+---
+layout: default
+title: "Architecture diagrams"
+permalink: /architecture/diagrams/
+description: "Source-pinned Civ13 architecture, UML diagrams, evidence boundaries and downloadable audit artifacts."
+image:
+ path: /public/img/architecture-overview.png
+ width: 1922
+ height: 573
+ alt: Civ13 architecture component overview
+---
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
+
+# Architecture diagrams
+
+Source pin: [`5bf351248de6050876fe5b53f91209a970cc5668`](https://github.com/Civ13/Civ13/tree/5bf351248de6050876fe5b53f91209a970cc5668). These are static abstractions, not exhaustive runtime execution paths. Select an image or SVG link to zoom; editable sources are alongside each view.
+
+## System overview and boundaries
+
+### System components
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/diagrams/01-system-components.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/diagrams/01-system-components.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/diagrams/01-system-components.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/diagrams/01-system-components.mmd' | relative_url }})
+
+### Core domain types
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/diagrams/02-domain-types.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/diagrams/02-domain-types.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/diagrams/02-domain-types.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/diagrams/02-domain-types.mmd' | relative_url }})
+
+### Player input dispatch
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/diagrams/03-input-dispatch.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/diagrams/03-input-dispatch.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/diagrams/03-input-dispatch.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/diagrams/03-input-dispatch.mmd' | relative_url }})
+
+### Lighting lifecycle
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/diagrams/04-lighting-lifecycle.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/diagrams/04-lighting-lifecycle.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/diagrams/04-lighting-lifecycle.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/diagrams/04-lighting-lifecycle.mmd' | relative_url }})
+
+### Lighting call-name candidates (not proven calls)
+
+This larger graph is provided as a separate zoomable SVG to keep this page lightweight.
+
+[SVG]({{ '/public/architecture/2026-10-20/diagrams/05-lighting-call-candidates.svg' | relative_url }}) · [DOT]({{ '/public/architecture/2026-10-20/diagrams/05-lighting-call-candidates.dot' | relative_url }})
+
+### NanoUI interaction boundary
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/diagrams/06-nanoui-boundary.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/diagrams/06-nanoui-boundary.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/diagrams/06-nanoui-boundary.puml' | relative_url }})
+
+## Runtime and gameplay
+
+### Runtime ownership
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/01_runtime_components.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/runtime/01_runtime_components.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/runtime/01_runtime_components.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/01_runtime_components.mmd' | relative_url }})
+
+### Round lifecycle
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/02_round_lifecycle.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/runtime/02_round_lifecycle.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/runtime/02_round_lifecycle.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/02_round_lifecycle.mmd' | relative_url }})
+
+### Movement and collision ownership
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/03_movement_sequence.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/runtime/03_movement_sequence.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/runtime/03_movement_sequence.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/03_movement_sequence.mmd' | relative_url }})
+
+### Combat dispatch
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/04_combat_dispatch.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/runtime/04_combat_dispatch.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/runtime/04_combat_dispatch.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/04_combat_dispatch.mmd' | relative_url }})
+
+### Crafting transaction
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/05_crafting_sequence.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/runtime/05_crafting_sequence.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/runtime/05_crafting_sequence.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/05_crafting_sequence.mmd' | relative_url }})
+
+### Research model
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/06_research_model.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/runtime/06_research_model.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/runtime/06_research_model.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/06_research_model.mmd' | relative_url }})
+
+### Animal AI states
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/07_animal_ai.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/runtime/07_animal_ai.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/runtime/07_animal_ai.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/07_animal_ai.mmd' | relative_url }})
+
+### Research prerequisites (dependency graph)
+
+This larger graph is provided as a separate zoomable SVG to keep this page lightweight.
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/08_research_prerequisites.svg' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/08_research_prerequisites.mmd' | relative_url }}) · [DOT]({{ '/public/architecture/2026-10-20/runtime/08_research_prerequisites.dot' | relative_url }})
+
+### Process lifecycle
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/runtime/09_process_state.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/runtime/09_process_state.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/runtime/09_process_state.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/runtime/09_process_state.mmd' | relative_url }})
+
+## Persistence and services
+
+### Help service sequence
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/persistence-services/help-sequence.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/persistence-services/help-sequence.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/persistence-services/help-sequence.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/persistence-services/help-sequence.mmd' | relative_url }})
+
+### Persistence components
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/persistence-services/persistence-components.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/persistence-services/persistence-components.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/persistence-services/persistence-components.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/persistence-services/persistence-components.mmd' | relative_url }})
+
+### Restart recovery
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/persistence-services/restart-state.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/persistence-services/restart-state.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/persistence-services/restart-state.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/persistence-services/restart-state.mmd' | relative_url }})
+
+### Save and load sequence
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/persistence-services/save-load-sequence.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/persistence-services/save-load-sequence.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/persistence-services/save-load-sequence.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/persistence-services/save-load-sequence.mmd' | relative_url }})
+
+### External services
+
+
+
+[SVG]({{ '/public/architecture/2026-10-20/persistence-services/services-components.svg' | relative_url }}) · [PNG]({{ '/public/architecture/2026-10-20/persistence-services/services-components.png' | relative_url }}) · [PUML]({{ '/public/architecture/2026-10-20/persistence-services/services-components.puml' | relative_url }}) · [MMD]({{ '/public/architecture/2026-10-20/persistence-services/services-components.mmd' | relative_url }})
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
diff --git a/architecture/persistence.md b/architecture/persistence.md
new file mode 100644
index 0000000..4a9e91b
--- /dev/null
+++ b/architecture/persistence.md
@@ -0,0 +1,110 @@
+---
+layout: default
+title: "Persistence and services"
+permalink: /architecture/persistence/
+description: "Source-pinned Civ13 architecture, UML diagrams, evidence boundaries and downloadable audit artifacts."
+image:
+ path: /public/img/architecture-overview.png
+ width: 1922
+ height: 573
+ alt: Civ13 architecture component overview
+---
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
+
+# Persistence and service architecture audit
+
+Scope: static read-only audit of Civ13 master commit `5bf351248de6050876fe5b53f91209a970cc5668`. No compilation, native runtime, paid model request, service action, or deployment was performed. Diagrams describe selected architecture-level paths and explicit branch families, not an exhaustive dynamic execution proof. Files present in the repository do not establish deployment. Mermaid component-like flowcharts are not formal UML component syntax.
+
+## Production boundary and ownership
+
+The main DME includes persistence functions, restart transaction, lifecycle control, durable graph/contract/timer/environment/world code, player reclaim, loader, and saver. It also includes the Help service, Python control process, preferences, and webhook code. `immutable_capture.dm` is absent from the main DME and appears in isolated test includes; the private gameplay bridge explicitly states it is not included. Do not conflate optional/test source with live production paths.
+
+Sources: [civ13.dme:1111-1124](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/civ13.dme#L1111-L1124); [civ13.dme:1215-1245](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/civ13.dme#L1215-L1245); [code/modules/gameplay_bridge/bridge.dm:1-4](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/gameplay_bridge/bridge.dm#L1-L4).
+
+`map_storage` is the serialization coordinator. `ticker.savemap` and `ticker.loadmap` wrap the backend with admission, exception handling and cleanup. `begin_persistence_operation` creates a unique `persistence_world_operation`; an active identity, not merely a boolean busy flag, owns release. It rejects existing operations, failed-load/dimension holds, active z reservations and conflicting restart intent. Backend and content entry are each one-shot. Direct Save_World/Load_World calls acquire an operation too, but the ticker load wrapper additionally supplies the preflight/clear/metadata/reclaim lifecycle; direct backend calls must not be modeled as equivalent to full ticker restoration.
+
+Sources: [code/modules/persistence/functions.dm:290-365](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/functions.dm#L290-L365); [code/modules/persistence/functions.dm:400-464](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/functions.dm#L400-L464).
+
+## Save graph and completed generations
+
+1. Admit the operation, prepare durable account ownership, capture supported durable world and round state, generate a round-v1/v2 identity.
+2. If a completed generation exists, invalidate the old backup marker, copy the old generation files, and copy its completion marker last. Only then invalidate the active marker. This preserves a prior completed generation before replacement.
+3. Write map metadata; for each z-level create a native savefile containing version, dimensions and generation. Traverse turfs and recursively selected objects/mobs; serialize changed fields, contents, and typed list/value envelopes. Explicit list identity preserves aliases/cycles.
+4. Finalize the separate durable graph (when opted in), write round.json, then publish save_complete.txt last. A partial save without that marker is not an accepted recovery point.
+
+The serializer excludes clients, map metadata objects, ignored types, should_save=false objects, spatial/session identity fields and `persistence_runtime_var` fields. This custom serializer visits tmp fields: tmp alone does not guarantee exclusion. `before_save_context` can participate through owned export frames and declared save transfers. A cross-z movable reference in a per-level object graph is rejected, not silently flattened. The separate durable metadata graph binds existing per-level entries without constructing a second leader/body.
+
+Sources: [code/modules/persistence/saving.dm:9-181](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/saving.dm#L9-L181); [code/modules/persistence/functions.dm:14-76](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/functions.dm#L14-L76); [code/modules/persistence/durable_graph.dm:1-109](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/durable_graph.dm#L1-L109).
+
+Durable metadata is opt-in by exact map profile, not universal world persistence. Schemas cover map/faction/research/economic state, environment, selected area/weather fields, timers, and bounded faction icon pixels. Timers and clock fields encode remainders/origins instead of copying a previous process clock. Capture rejects active seasonal/weather/lighting transitions. Extending map subtypes or adding state requires reviewing the schema and timer inventory, not merely adding a field.
+
+Sources: [code/modules/persistence/durable_contract.dm:1-86](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/durable_contract.dm#L1-L86); [code/modules/persistence/durable_world.dm:1-45](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/durable_world.dm#L1-L45); [code/modules/persistence/durable_timers.dm:1-70](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/durable_timers.dm#L1-L70).
+
+## Load, rebuild, and reconnect
+
+`ticker.loadmap` owns admission across dimension preparation, full save validation, mutation, restoration, and player callbacks. Validation checks marker, matching map metadata, round identity, dimensions, full grids, valid types, entry references, duplicate player ownership, and durable graph/schema. Dimension growth has its own reservation/recovery gate; rejection can retain a hold to prevent overwrite.
+
+After preflight, the wrapper snapshots the header, verifies an expected restart generation, requires durable world idle, marks mutation started, resets player restoration, suspends durable callbacks, and clears the map. The backend allocates every turf before loading references, indexes same-level turfs, loads recursive entries, invokes after_load, registers restored players, then rebuilds opacity and lighting. Metadata, durable world, and round phase/lighting are restored afterward. A post-mutation failure latches recovery; this is fail-closed restoration, not rollback of a partially mutated world.
+
+Sources: [code/modules/persistence/functions.dm:420-464](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/functions.dm#L420-L464); [code/modules/persistence/functions.dm:684-754](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/functions.dm#L684-L754); [code/modules/persistence/loading.dm:183-354](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/loading.dm#L183-L354).
+
+Durable player ownership is a normalized non-guest authenticated ckey, distinct from transient client/key fields. Preparation rejects ambiguous ownership; reconnect only claims one living, located, unoccupied restored human, checks playing/server bans, consumes the reservation, transfers the authenticated client's key through normal Login, and deletes the lobby. Restart recovery waits until its intent is consumed before reclaiming waiting clients. No Help conversation is restored with the body.
+
+Sources: [code/modules/persistence/player_reclaim.dm:1-116](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/player_reclaim.dm#L1-L116); [code/modules/persistence/restart_transaction.dm:156-185](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/restart_transaction.dm#L156-L185).
+
+## Restart state machine and deployment lifecycle
+
+The validated restart transaction supports native BYOND durable metadata profiles (reported in source as Gaia/Europe) and explicitly rejects OpenDream. It saves and validates a completed generation, writes a one-shot restart_intent.json binding generation/metadata/round hashes, rereads it, revalidates ownership, then requests native restart or graceful world deletion. Startup detects the intent before normal setup, holds fresh-round/player paths, prepares dimensions, validates the same generation, imports once, consumes only the matching intent and then releases player restoration. Malformed/mismatched intent, failed dimension admission, incomplete import, or failed intent deletion retains a recovery hold. An import that already began and failed is not retried into the same mutated world.
+
+There are two distinct persistence boot routes. PERSISTENCE configuration autoloads a matching completed ordinary save; an explicit restart intent applies independently of that gamemode. Scheduled maintenance is a separate save -> completion-marker check -> ordinary Reboot path, rather than `persistence_restart.execute`. This divergence is a review target, not a demonstrated defect: its recovery contract depends on ordinary PERSISTENCE autoload, whereas the transaction binds a specific generation.
+
+Sources: [code/modules/persistence/restart_transaction.dm:77-185](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/restart_transaction.dm#L77-L185); [code/setup.dm:136-172](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/setup.dm#L136-L172); [code/world.dm:356-398](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L356-L398).
+
+The compiled local lifecycle Topic endpoint requires IPv4 loopback, configured token/revision, exact allowed keys/actions and boot-session/operation binding. It exposes status, bounded diagnostics and save_shutdown, not arbitrary eval or shell. Operations have replay protection and a bounded operation count. The Python Nomads supervisor is explicitly restricted to port 1714 and NOMADS_EUROPE: fetch exact commit, detached build, generate catalog, switch that isolated checkout's map include, require clean compilation, hash binaries, ensure owned process/session identity, defer update with clients or busy save, request bound save/shutdown, snapshot validated files, launch a fresh run directory, and wait for matched restoration/readiness. Unexpected exit, mismatch or timeout preserves evidence rather than automatically starting a fresh round. These are source contracts, not proof that this supervisor is installed or running.
+
+Sources: [code/modules/persistence/nomads_lifecycle.dm:70-108](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/persistence/nomads_lifecycle.dm#L70-L108); [scripts/nomads-lifecycle/supervisor.py:222-422](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/scripts/nomads-lifecycle/supervisor.py#L222-L422).
+
+## External service and file boundaries
+
+- Help: authenticated client verb -> service availability/rate-limit/queue admission -> bounded JSON request and ready marker -> separate Python bridge -> approved player corpus/recipe/wiki retrieval -> configured Ollama HTTP endpoint -> atomic bounded response -> DM id and client-generation checks -> escaped/bounded renderer. Account identity is salted before spooling; conversation history is client-session-only with generation and action tokens. There are eight queue slots; configured worker count is one or two. Bridge startup clears old spool requests instead of replaying them. HTTP uses a separate deadline-bounded child, disables environment proxies and redirects, and optional credentials come from an environment variable. The model has no tools/actions. File deletion is not encryption or guaranteed crash-time erasure.
+- Discord: world messaging loop polls SQL/discord2ooc, discord2admin, discord2dm, discord2ban and discord2unban files, splits delimiter fields, dispatches chat/moderation and deletes consumed files. The local file writer and OS permissions are therefore a privileged integration boundary. This checkout does not contain the deployed bot implementation or establish who can write those files.
+- Preferences: despite the preferencesSQLite folder and SQL path names, inspected code reads/writes delimiter-encoded SQL/charprefs.txt. Existing-account update deletes/rebuilds that file; there is no database transaction shown on this path. Do not label it SQLite storage based on the folder name.
+- Webhooks: optional configured address/key gates outgoing asynchronously spawned world.Export calls with URL-encoded JSON. Login webhook fields can include ckey/IP/CID. Endpoint configuration, logging and access should be treated as privacy/security boundaries; no deployed endpoint was inspected.
+- World Topic: rate-limited public status/ping dispatch uses registered world_topic subtypes, with lifecycle handled separately through the restricted endpoint. This is different from object Topic/UI dispatch.
+- Script control: native `/process/python/execute` rate-limits invocation and delegates to shell Python scripts (sudo on Unix); OpenDream instead permits only fixed mapswap/restart spool actions. The process fire method is a no-op, so its registration does not imply autonomous command execution.
+
+Sources: [code/game/mob/player_help.dm:24-218](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/player_help.dm#L24-L218); [code/game/mob/player_help.dm:291-405](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/player_help.dm#L291-L405); [scripts/player_help_bridge.py:303-359](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/scripts/player_help_bridge.py#L303-L359); [scripts/player_help_bridge.py:462-641](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/scripts/player_help_bridge.py#L462-L641); [code/world.dm:183-232](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L183-L232); [code/world.dm:400-471](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L400-L471); [code/modules/client/preferencesSQLite/preferences_saving&loading&del.dm:1-124](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/client/preferencesSQLite/preferences_saving%26loading%26del.dm#L1-L124); [code/modules/webhooks/webhooks.dm:31-49](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/webhooks/webhooks.dm#L31-L49); [code/processes/python.dm:1-58](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/python.dm#L1-L58).
+
+## Launch, CI, and optional tooling
+
+Legacy launch.py and updateserver.py pull/reset a configured checkout, generate the crafting catalog, invoke DreamMaker, copy binaries/config and (launch only) start trusted DreamDaemon. These are not the transaction supervisor. Several shell steps use os.system without checked return values, unlike the checked catalog generation. Review this legacy deployment path before relying on failure containment; no failed deployment was reproduced.
+
+The main CI workflow uses reusable change selection, an offline evidence-checker job and a build job with conditional compilation/native fixture lanes. BYOND is pinned to 516.1681. Documentation-only changes can skip game compilation; extensive/new-test selectors govern many native fixtures and negative controls. A source-defined CI step is not a passing run, and fixture success is not connected-client or deployed-server acceptance. Other repository workflows cover tooling, documentation and review automation; this report does not certify their external secrets or execution history.
+
+Bot service control is default-off and its README explicitly says not to install/enable the draft unit yet: independent game supervision and bot-restart/game-survival acceptance are prerequisites. The helper's fixed service actions, nonblocking lock and cooldown are narrower than the legacy shell pathway. The gameplay bridge and immutable capture are separate non-production/test mechanisms at this commit, not live Help or live save replacements.
+
+Sources: [scripts/travis_pre_byond.sh:1-32](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/scripts/travis_pre_byond.sh#L1-L32); [scripts/launch.py:1-53](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/scripts/launch.py#L1-L53); [scripts/updateserver.py:1-46](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/scripts/updateserver.py#L1-L46); [.github/workflows/test.yml:58-172](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/.github/workflows/test.yml#L58-L172); [scripts/bot-service/README.md:1-92](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/scripts/bot-service/README.md#L1-L92); [code/modules/gameplay_bridge/bridge.dm:1-4](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/gameplay_bridge/bridge.dm#L1-L4); [tests/world_save/immutable_capture.dme:1-14](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/tests/world_save/immutable_capture.dme#L1-L14).
+
+## Architectural risks and next verification targets
+
+1. **Yielding snapshot semantics:** completed generation integrity is stronger than atomic gameplay snapshot semantics. Tick checks and hooks yield. Audit every state-changing subsystem's save gate and verify invariants under interleaving; do not claim transactional world freeze.
+2. **Schema/exclusion maintenance:** changed-vars traversal and explicit tmp exclusions create a continuing obligation for new fields, callbacks, timers, caches and cross-z references. Pair schema changes with disk roundtrip and legacy migration controls.
+3. **Recovery availability:** fail-closed holds protect data from overwrite but require an operator recovery runbook. Preserve the original compiled map and matched complete files; distinguish preflight rejection from post-mutation failure.
+4. **Two restart contracts:** consolidate or explicitly document scheduled-maintenance ordinary autoload versus generation-bound transactional restart. Test both, including interrupted writes and intent consumption failures.
+5. **File IPC privilege and durability:** Discord moderation, preference rewrites, Help and supervisor files have different formats and trust assumptions. Review ownership/permissions, concurrent writers, restart cleanup, partial writes and retention separately; one spool's safeguards do not automatically cover another.
+6. **Legacy deployment versus owned supervisor:** legacy shell launch has different error/ownership semantics and elevated commands. Confirm which path the host actually uses before making operational guarantees.
+7. **Evidence separation:** tests, disabled sources, authored CI lanes, historical documentation and actual deployed behavior are distinct evidence classes. This audit establishes static contracts only.
+
+## Diagram index
+
+- `persistence-components.mmd`: compiled persistence relationships and durable/runtime boundaries.
+- `save-load-sequence.mmd`: save and full ticker-load order with preflight/failure branches.
+- `restart-state.mmd`: one-shot restart and fail-closed recovery lifecycle.
+- `help-sequence.mmd`: client-session/model/file trust boundaries.
+- `services-components.mmd`: external boundaries with explicitly optional/disabled paths.
+
+PlantUML counterparts (`.puml`) are provided for each diagram. They express actual component, sequence or state diagram syntax; rendering is handled by the enclosing audit. Mermaid files remain available.
+
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
diff --git a/architecture/runtime.md b/architecture/runtime.md
new file mode 100644
index 0000000..c98e2bc
--- /dev/null
+++ b/architecture/runtime.md
@@ -0,0 +1,138 @@
+---
+layout: default
+title: "Runtime and gameplay"
+permalink: /architecture/runtime/
+description: "Source-pinned Civ13 architecture, UML diagrams, evidence boundaries and downloadable audit artifacts."
+image:
+ path: /public/img/architecture-overview.png
+ width: 1922
+ height: 573
+ alt: Civ13 architecture component overview
+---
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
+
+# Runtime and gameplay architecture audit
+
+Commit: `5bf351248de6050876fe5b53f91209a970cc5668` (Civ13/Civ13 master snapshot supplied for this audit). Read-only static analysis. No server, compiler, live client, deployment, publication, or paid service was used. All source links pin this commit. AGENTS.md was read; its operational guidance is not treated as proof of runtime behavior.
+
+## Scope and interpretation
+
+This report covers startup, process scheduling, round phases, human movement/input, item combat/projectiles, crafting, faction research, simple-animal AI, and delayed-action ownership. Mermaid files describe component, class, sequence, and state abstractions. They are not a claim to enumerate every concrete execution trace. Random choices, arbitrary player inputs, map-specific overrides, spawned callbacks, configuration recipes and unlimited repeated rounds make that set unbounded. The accompanying inventory covers the full tracked DM tree.
+
+Evidence labels used below:
+- **Proven source edge**: a call or state assignment is present at the cited location.
+- **Dynamic edge**: receiver type, hook, callback, map, recipe or registered object determines the implementation at runtime.
+- **Unresolved activation**: code is compiled, but an ordinary startup path to running it was not established by this review.
+- **Review concern**: architectural risk or stale documentation, not a verified gameplay defect.
+
+## 1. Startup and scheduling ownership
+
+Pre-map `/datum/global_init/New()` creates game ID, reference registries, configuration and chemistry definitions, then deletes itself. Native map construction occurs before `/world/New()`. World startup records compiled dimensions and detects persistence recovery before yielding, runs configuration post-load and startup hooks, builds materials and the shared research registry, creates `/processScheduler`, and schedules setup. The process scheduler is set up before `setup_everything()` initializes occupations, movable atoms, areas, access-list files, recipe files and dictionary data. These are interleaved cooperative operations, not an atomic initialization transaction. [code/world.dm:27-44](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L27-L44) [code/world.dm:81-123](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L81-L123) [code/setup.dm:1-28](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/setup.dm#L1-L28) [code/setup.dm:83-120](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/setup.dm#L83-L120)
+
+`/process/ticker/setup()` instantiates the gameticker and schedules pregame plus server watchdog, status-file, messaging and persistence loops. `/world/start_serverswap_loop` starts or restarts the legacy scheduler and separately creates/starts the movement machine. These background loops exist in addition to process objects. The persistence loop schedules saving and maintenance reboot; the messaging loop polls file-based external input. [code/processes/ticker.dm:6-28](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/ticker.dm#L6-L28) [code/world.dm:348-399](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L348-L399) [code/world.dm:400-502](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L400-L502)
+
+The scheduler discovers all compiled `/process` subtypes, constructs each, calls setup, and tracks name, priority and queue membership. In this revision `is_subsystem_member` defaults FALSE; no production assignment overriding it was found. The `SSUtility`, `SSCombat`, etc. headings in `process_list` are comments, not actual parent subsystems. `deferSetupFor(/process/ticker)` records a list but the shown `setup()` enumeration does not consult that list. Therefore the startup diagram does not claim ticker setup is deferred until all other processes finish. [code/processes/__processScheduler.dm:74-98](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/__processScheduler.dm#L74-L98) [code/processes/_process.dm:40-49](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/_process.dm#L40-L49) [code/processes/__processes.dm:1-49](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/__processes.dm#L1-L49)
+
+### Scheduler execution contract
+
+1. `start()` installs a new run token, sets interval from `world.tick_lag`, orders processes by priority and spawns the main loop. A replacement start retires the prior sleeping scheduler invocation through token inequality.
+2. Each cycle checks running processes, queues enabled idle processes whose game-state and interval gates pass, then relays eligible queued work within a tick-usage envelope.
+3. `relayProcess()` has `waitfor = FALSE`; it initializes a missing work snapshot and calls the process wrapper. `started()` marks running, records timestamps and invokes `onStart`; `process()` invokes `fire` unless paused; `finished()` returns idle and keeps only unfinished nonempty budget snapshots.
+4. Ordinary priorities copy registered lists and remove visited entries. VERY_HIGH aliases the live list and skips both removal and the ordinary per-process tick check. These macros affect movement/projectile/throwing semantics and must be represented explicitly in performance reasoning.
+5. Hung states escalate by elapsed time, then the scheduler constructs a replacement of the old runtime type, copies selected configuration/state, replaces owner maps/list entries and kills the old instance. Disabled/paused/state-gated are distinct from queue/running status.
+
+[code/processes/__processScheduler.dm:100-209](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/__processScheduler.dm#L100-L209) [code/processes/__processScheduler.dm:243-306](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/__processScheduler.dm#L243-L306) [code/processes/__processScheduler.dm:399-407](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/__processScheduler.dm#L399-L407) [code/processes/_process.dm:134-159](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/_process.dm#L134-L159) [code/processes/_process.dm:182-273](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/_process.dm#L182-L273) [code/processes/_process.dm:314-348](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/_process.dm#L314-L348) [code/processes/___defines.dm:28-33](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/___defines.dm#L28-L33)
+
+The source catalogue contains 37 directly included setup declarations under `code/processes/`; it intentionally does not claim this is the entire compiled `/process` subtype universe. See `process_catalog.md/json`. Major dispatches are mob -> `Life` (1 second), object -> `process_interval` (2 seconds), map -> `tick` (2 seconds), ticker -> `process` (2 seconds), research benches -> `analysis_tick` (10 seconds), and projectile -> `process` (configured 0.03 second). These are ideal schedule expressions, not measured frequency or guaranteed wall-clock latency. [code/processes/mob.dm:3-53](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/mob.dm#L3-L53) [code/processes/obj.dm:1-27](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/obj.dm#L1-L27) [code/processes/map.dm:3-12](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/map.dm#L3-L12) [code/processes/ticker.dm:6-45](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/ticker.dm#L6-L45) [code/processes/research_tree.dm:9-29](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/research_tree.dm#L9-L29) [code/processes/projectile.dm:3-40](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/projectile.dm#L3-L40)
+
+### Other timing mechanisms
+
+- `/process/scheduler` owns `/datum/scheduled_task` entries and dynamically calls procedure/argument lists with pre/post events; source-bound tasks register destruction callbacks. This is a task scheduler inside the legacy process scheduler, not the same object. [code/processes/scheduler.dm:7-34](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/scheduler.dm#L7-L34) [code/processes/scheduler.dm:52-132](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/scheduler.dm#L52-L132)
+- StonedMC, failsafe, base subsystem and timer sources are compiled, and `Master` is globally instantiated. Its constructor enumerates subsystem types, but does not itself invoke the full Initialize/StartProcessing path. `Master.Initialize()` does initialize and start processing when called. This review found internal recovery paths but did not establish ordinary startup activation of that method. The timer/controller branch is shown dashed, not claimed absent or running. A dynamic/admin entry could still activate it. [civ13.dme:114-119](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/civ13.dme#L114-L119) [code/controllers/mc/master.dm:12-96](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/controllers/mc/master.dm#L12-L96) [code/controllers/mc/master.dm:135-225](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/controllers/mc/master.dm#L135-L225)
+- Native `spawn`, `sleep`, `walk`, `walk_to`, event hooks and async procs remain distributed throughout gameplay. A single process graph cannot represent their complete timing behavior.
+
+## 2. Round lifecycle
+
+The live gameticker state variable begins PREGAME. `pregame()` waits on persistence startup hold and exits if the round was restored. It counts down a 90-second lobby under `round_progressing`, with map voting able to wait independently; zero advances to SETTING_UP. `setup()` retries or returns to PREGAME when persistence/save/admission gates do not permit a fresh round. Success sets PLAYING, resets occupations, creates ready characters, collects minds, equips roles, starts time-of-day logic and invokes roundstart hooks. Restored rounds bypass fresh character/equipment/map setup. [code/game/gameticker.dm:6-35](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/gameticker.dm#L6-L35) [code/game/gameticker.dm:45-157](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/gameticker.dm#L45-L157)
+
+Map tick checks faction boundaries, elimination conditions, map-specific win conditions and events; the base win-condition implementation sets `ticker.finished`. Ticker does not run every native tick: the process interval is two seconds. For normal rounds its process transitions PLAYING -> FINISHED and spawns delayed roundend/reboot handling; admin `delay_end`, epoch-swap state and persistence rechecks can alter that path. A persistence-active round clears finished and stays PLAYING. World reboot separately checks save/restart ownership and startup holds before native restart or OpenDream supervisor behavior. [code/game/objects/map_metadata/_map_metadata.dm:477-522](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/map_metadata/_map_metadata.dm#L477-L522) [code/game/objects/map_metadata/_map_metadata.dm:684-735](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/map_metadata/_map_metadata.dm#L684-L735) [code/game/gameticker.dm:193-245](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/gameticker.dm#L193-L245) [code/world.dm:235-277](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L235-L277)
+
+`02_round_lifecycle.mmd` is the gameticker abstraction, not a lifecycle diagram for every map metadata subtype. Map-specific state variables and hooks are dynamic extensions. In particular, a map's `game_over`, victory timer and `ticker.finished` are not universally synonymous.
+
+## 3. Input, movement and collision
+
+Input has native cardinal/diagonal handlers and held-direction start/stop verbs. The delayed mob-construction callback adds a non-lobby client to `movementMachine_clients`; the movement loop selects cardinal or combined diagonal intent, checks movement ownership/delay, then asynchronously calls `client.Move`. It removes the client while movement is busy and re-adds after the current delay. The loop requests a 0.01-second interval but this is not evidence BYOND delivers 100 Hz simulation. [code/game/mob/mob.dm:30-44](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/mob.dm#L30-L44) [code/game/mob/mob_movement.dm:97-145](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/mob_movement.dm#L97-L145) [code/game/mob/mob_movement.dm:977-1195](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/mob_movement.dm#L977-L1195) [code/movementMachine.dm:24-98](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/movementMachine.dm#L24-L98) [code/movementMachine.dm:102-126](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/movementMachine.dm#L102-L126)
+
+`client.Move` is a large policy junction: canmove/moving/delay checks, map boundaries, prone/lying actions, equipment, stamina, pulling, riding/vehicles and movement timing. It eventually uses polymorphic mob movement. Living Move coordinates buckle/drone/restraint/pull behavior, movable Move owns the native offset seam, and BYOND collision invokes Bump. Human Bump tries the shared mining operation before inherited living Bump's deferred pushing. [code/game/mob/mob_movement.dm:193-283](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/mob_movement.dm#L193-L283) [code/game/mob/mob_movement.dm:284-340](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/mob_movement.dm#L284-L340) [code/game/mob/mob_movement.dm:650-700](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/mob_movement.dm#L650-L700) [code/game/mob/living/living.dm:502-560](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/living.dm#L502-L560) [code/game/mob/living/carbon/carbon.dm:392-405](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/carbon/carbon.dm#L392-L405) [code/game/mob/living/living.dm:45-80](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/living.dm#L45-L80)
+
+The human physical sub-tile adapter is compiled but `human_subtile_enabled` defaults FALSE. It has restricted shape/direction/state eligibility and runtime ownership/capsule machinery. The movement diagram treats its enabled path as opt-in, not normal production behavior. Its presence does not establish real-client timing acceptance. [civ13.dme:230](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/civ13.dme#L230) [code/game/mob/living/carbon/human/subtile_movement.dm:1-74](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/carbon/human/subtile_movement.dm#L1-L74) [code/game/mob/living/carbon/human/subtile_movement.dm:230-246](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/carbon/human/subtile_movement.dm#L230-L246)
+
+### Shared delayed-action boundary
+
+`do_after` locks ordinary repeated actions, captures actor location, active hand and target location, shows progress, then sleeps and revalidates incapacity/movement/hand/target. It clears the lock and progress at completion. Optional mining context claims and validates actor+turf ownership; gameplay bridge context is conditional on `CIV13_GAMEPLAY_BRIDGE` and must not be flattened into the default signature. [code/_helpers/mobs.dm:190-280](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/_helpers/mobs.dm#L190-L280)
+
+Click and bump mining reserve actor/turf before a spawned worker, record exact tool, origin and physical step offsets, and revalidate before committing. `try_bump_mining -> start_pickaxe_mining -> pickaxe_mining_action.perform -> do_after(mining_context=...)` is a distinct ownership-sensitive path, not just an inherited generic attack call. [code/game/turfs/floor_attackby.dm:677-817](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/turfs/floor_attackby.dm#L677-L817)
+
+## 4. Combat and polymorphic item interaction
+
+`atom.Click -> usr.ClickOn` is the common mouse entry. ClickOn first checks target and next-click deadline, then routes modifiers, special equipment/vehicle branches, active-hand/self interactions, adjacent versus ranged interaction, or unarmed action. Do not interpret every click as an attack. [code/_onclick/click.dm:7-74](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/_onclick/click.dm#L7-L74) [code/_onclick/click.dm:198-287](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/_onclick/click.dm#L198-L287)
+
+Item dispatch order is explicit: resolve turf attack first when appropriate; then target `attackby`; then item `attack_obj` for objects. A truthy resolved result suppresses ordinary afterattack paths. Living target `attackby` can route surgery; otherwise item `attack` applies eligibility, stamina, logging, cooldown and animation, asks the target to resolve the hit, and invokes `apply_hit_effect -> hit_with_weapon` for a resolved hit. Target/item subclass overrides determine actual armor, hit-zone and special-effect branches. [code/_onclick/item_attack.dm:22-74](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/_onclick/item_attack.dm#L22-L74) [code/_onclick/item_attack.dm:92-121](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/_onclick/item_attack.dm#L92-L121)
+
+Gun `afterattack` routes aiming/PreFire or Fire; Fire uses weapon-specific ammunition acquisition and calls projectile processing/launch. Projectiles register and travel through their own process queue; `process`, `handleTurf`, `attack_mob`, `do_bullet_act` and target `bullet_act` decide collision, miss, penetration and damage. `process/projectile.reset_current_list` limits the current list to 500 and deletes the excess; this is explicit overload behavior, not proof of a measured problem. [code/modules/projectiles/gun.dm:138-193](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/projectiles/gun.dm#L138-L193) [code/modules/projectiles/gun.dm:276-375](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/projectiles/gun.dm#L276-L375) [code/modules/projectiles/gun.dm:460-524](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/projectiles/gun.dm#L460-L524) [code/modules/projectiles/projectile.dm:175-239](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/projectiles/projectile.dm#L175-L239) [code/modules/projectiles/projectile.dm:308-443](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/projectiles/projectile.dm#L308-L443) [code/modules/projectiles/projectile.dm:472-728](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/projectiles/projectile.dm#L472-L728) [code/modules/projectiles/projectile.dm:732-821](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/projectiles/projectile.dm#L732-L821) [code/processes/projectile.dm:34-40](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/projectile.dm#L34-L40)
+
+`04_combat_dispatch.mmd` shows the default melee and gun paths. Alternative overrides (explosions, thrown weapons, spells, surgery, vehicles, special weapon actions) remain extensions, not omissions claimed unreachable.
+
+## 5. Crafting and research
+
+Recipes have both code-defined variants and config-driven records. Setup reads `config/crafting/material_recipes*` lines containing 13 comma-separated fields into global/faction lists. `material.get_recipes_civs` chooses race/faction and map/civilization research values. Generation resolves result path strings with `text2path`, gates by research-node completion when mapped, otherwise legacy three-axis research thresholds, and applies era/material/feature checks before creating stack-recipe datums. This is a data-to-type construction boundary. [code/setup.dm:83-107](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/setup.dm#L83-L107) [code/game/objects/items/stacks/civ_recipes.dm:19-144](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/items/stacks/civ_recipes.dm#L19-L144)
+
+The stack menu Topic path validates actor state and held source, resolves recipe/sublist/multiplier, and uses `H.can_build_recipe` to serialize the operation. `produce_recipe` is a large content-specific transaction: feature gates, subtype-specific prompts and temporary constructions, derived time, `do_after`, post-wait special revalidation, debit with `use(required,H)`, dynamic `new recipe.result_type` and post-construction configuration. Craft cancellation and payment semantics are branch-specific. In particular, wood-handle crafting keeps the exact handle/source through the wait, revalidates both, and removes the actual equipment slot only after successful main stack debit. Do not generalize that transaction guarantee to every recipe branch without a separate branch audit. [code/game/objects/items/stacks/stack.dm:298-335](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/items/stacks/stack.dm#L298-L335) [code/game/objects/items/stacks/stack.dm:1805-1830](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/items/stacks/stack.dm#L1805-L1830) [code/game/objects/items/stacks/stack.dm:1898-1944](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/items/stacks/stack.dm#L1898-L1944) [code/game/objects/items/stacks/stack.dm:2355-2437](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/items/stacks/stack.dm#L2355-L2437)
+
+The new research architecture separates shared immutable-ish node definitions (`research_nodes`, recipe requirement index) from mutable map-owned faction progress. Benches register themselves globally, own faction/tier/assignment/queue, and operate under leader/director/researcher permissions. The process iterates benches and calls analysis_tick; the bench advances its queue, checks mode, tier, prerequisites, already-done state and an online authorized researcher, then credits progress and refreshes viewers. [code/modules/research_tree/research_node.dm:13-74](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_node.dm#L13-L74) [code/modules/research_tree/research_node.dm:159-234](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_node.dm#L159-L234) [code/modules/research_tree/research_bench.dm:23-94](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_bench.dm#L23-L94) [code/modules/research_tree/research_bench.dm:105-207](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_bench.dm#L105-L207) [code/modules/research_tree/research_faction.dm:43-71](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_faction.dm#L43-L71) [code/modules/research_tree/research_faction.dm:200-232](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_faction.dm#L200-L232)
+
+`add_research_ticks` moves an entry into IN_PROGRESS and completes ANALYSIS when cost is reached; PROTOTYPE needs both accumulated study and a submitted prototype. Books can complete through the explicit book route; notes and reverse engineering add progress; coin inputs upgrade benches. `complete_node` marks faction DONE and prototype era capstones can increase the world's ordinal age. Global era progression does not imply every faction researched every node: `is_node_done` has explicit baseline-era semantics. [code/modules/research_tree/research_faction.dm:114-190](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_faction.dm#L114-L190) [code/modules/research_tree/research_faction.dm:214-232](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_faction.dm#L214-L232) [code/modules/research_tree/research_bench.dm:585-740](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_bench.dm#L585-L740)
+
+The generated `08_research_prerequisites.mmd` covers 93 direct node constructor registrations in the selected registry file, with 99 declared prerequisite edges. `research_nodes.json` preserves costs, tiers, modes and line numbers; `research_graph_checks.json` checks unresolved prerequisite IDs and duplicate IDs. It is a declared dependency graph, not proof that every research route is dynamically reachable in every map. Recipe-to-node mapping and baseline grants are separate from prerequisite edges.
+
+Research storage comments describe faction progress as round-scoped and bench variables as saver-owned. This report does not infer current serialization solely from those comments; persistence schema/import coverage belongs to the persistence audit.
+
+## 6. Life and AI
+
+`process/mob` dispatches `Life()` over `living_mob_list` and catches per-object exceptions. Human Life combines physiology, body/visual state, nutrition, stamina, environmental/health logic and content-specific rules; survival idle multiplier separately uses input inactivity plus action/movement clocks. Simple animal Life handles status, starvation, following and then `handle_ai`. [code/processes/mob.dm:12-53](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/mob.dm#L12-L53) [code/game/mob/living/carbon/human/human_life.dm:40-180](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/carbon/human/human_life.dm#L40-L180) [code/game/mob/living/simple_animal/simple_animal.dm:124-175](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/simple_animal/simple_animal.dm#L124-L175)
+
+Simple AI returns for unconscious/dead, client-owned, anchored or empty-server cases, and for various movement restrictions. Idle hunger can preempt general behavior. Behavior strings select scared/wander/hunt/defends/hostile; attack/alert runs more urgently while idle is throttled. Tactical handling adds IDLE/ALERT/ATTACK/TIRED stance logic, perception, faction eligibility, target loss, pursuit, surroundings destruction and attack. Hostile mode can transition directly from IDLE to ATTACK, so ALERT is not a mandatory intermediate state. [code/game/mob/living/simple_animal/simple_ai.dm:3-121](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/simple_animal/simple_ai.dm#L3-L121) [code/game/mob/living/simple_animal/hostile/tactical_ai.dm:131-265](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/simple_animal/hostile/tactical_ai.dm#L131-L265) [code/game/mob/living/simple_animal/hostile/tactical_ai.dm:266-438](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/simple_animal/hostile/tactical_ai.dm#L266-L438)
+
+Cover and friendly-fire helpers apply to human NPCs; arbitrary animal subtypes can override target and attack procedures. Dogs additionally have a dedicated fast follow process. Pathfinding/native walking can continue between Life dispatches, so AI is not a single closed four-state automaton. `07_animal_ai.mmd` explicitly labels the simplified combat stance graph and behavior dispatch. [code/game/mob/living/simple_animal/hostile/tactical_ai.dm:4-127](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/mob/living/simple_animal/hostile/tactical_ai.dm#L4-L127) [code/processes/dog.dm:3-46](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/dog.dm#L3-L46)
+
+## 7. Review concerns and concrete follow-on verification
+
+These are evidence-supported review targets, not asserted bugs:
+
+1. **Mixed scheduler ownership and stale comments.** Included MC/timer infrastructure, legacy process comments naming non-existent grouping owners, deferred-setup record without observed use, spawned loops and native walking create competing mental models. Verify actual startup with a fixture trace of process creation, ticker creation, loop starts and readiness. Do not assume declared controller files are active. Sources: startup/scheduler sections above.
+2. **Budget fairness depends on list shape and macros.** Ordinary loops retain work snapshots, VERY_HIGH uses live lists, and research fire iterates a fresh bench copy with a tick check rather than the same current-list resume protocol. Inspect large-list progress and mutation behavior with native tests before claiming fairness/starvation. [code/processes/___defines.dm:28-33](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/___defines.dm#L28-L33) [code/processes/research_tree.dm:16-28](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/research_tree.dm#L16-L28) [code/processes/_process.dm:147-159](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/_process.dm#L147-L159)
+3. **Movement recovery ownership deserves a targeted test.** Legacy scheduler start has a run token; movementMachine.start simply spawns another process loop, and watchdog recovery calls start on a stale last_run. The architecture exposes different restart contracts. Whether duplicate live movement loops occur requires a controlled stale/watchdog timing test, not source-only assertion. [code/processes/__processScheduler.dm:100-131](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/__processScheduler.dm#L100-L131) [code/movementMachine.dm:24-31](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/movementMachine.dm#L24-L31) [code/world.dm:466-500](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/world.dm#L466-L500)
+4. **Crafting is a content-heavy transaction hub.** `produce_recipe` spans hundreds of branches and yields at input/do_after; consumption, object creation and cancellation need per-family conservation tests. Recent handle/drill/electronics guards are explicit examples, not blanket coverage. [code/game/objects/items/stacks/stack.dm:298-335](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/items/stacks/stack.dm#L298-L335) [code/game/objects/items/stacks/stack.dm:1805-1944](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/items/stacks/stack.dm#L1805-L1944)
+5. **Research comment drift.** Bench analysis comments describe prototype submission as a shortcut rather than mandatory; executable `add_research_ticks` caps study until the prototype is submitted. UI/examine text should be checked against executable completion gates. [code/modules/research_tree/research_bench.dm:66-73](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_bench.dm#L66-L73) [code/modules/research_tree/research_faction.dm:181-189](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/modules/research_tree/research_faction.dm#L181-L189)
+6. **Cross-cutting mutable globals.** Map, ticker, job master, process-list singleton, registries and actor variables are shared across input, periodic updates and deferred work. Save/import, round transitions and object deletion must preserve reciprocal ownership and avoid treating process-local deadlines as durable state. This report establishes the boundary, not persistence correctness.
+7. **Dynamic dispatch limits static coverage.** Hooks use text-to-path and call; scheduled tasks use dynamic procedure/arguments; crafting resolves data strings to constructors; every `Life`, `attackby`, `Move`, map `tick` and object `process_interval` may resolve a subtype implementation. A sound complete may-call graph needs DM type/inheritance resolution and config/map variants, plus explicit unresolved edges. [code/hooks.dm:50-64](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/hooks.dm#L50-L64) [code/processes/scheduler.dm:108-132](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/processes/scheduler.dm#L108-L132) [code/game/objects/items/stacks/civ_recipes.dm:114-144](https://github.com/Civ13/Civ13/blob/5bf351248de6050876fe5b53f91209a970cc5668/code/game/objects/items/stacks/civ_recipes.dm#L114-L144)
+
+## Deliverables and checks
+
+- `01_runtime_components.mmd`: startup and runtime owners, including unresolved MC activation.
+- `02_round_lifecycle.mmd`: round-state and persistence branches.
+- `03_movement_sequence.mmd`: held/native input, movement, collision/mining ownership.
+- `04_combat_dispatch.mmd`: default item, melee and projectile dispatch.
+- `05_crafting_sequence.mmd`: menu-to-dynamic-construction transaction skeleton.
+- `06_research_model.mmd`: research data/ownership class model and gates.
+- `07_animal_ai.mmd`: simplified behavior and stance transitions.
+- `08_research_prerequisites.mmd`, `.dot` and `.svg`: generated declared node prerequisite graph.
+- `09_process_state.mmd`: legacy scheduler work/status transitions.
+- `process_catalog.md/json`, `research_nodes.json`, `research_graph_checks.json`: machine-readable evidence and source links.
+- `build_runtime_artifacts.py`: reproducible lexical extraction. Does not execute game code. Run `python build_runtime_artifacts.py --source /path/to/pinned-checkout --output /path/to/artifacts`. The report itself is curated, not regenerated by this script.
+
+Mermaid is editable diagram source. Eight equivalent focused PlantUML sources are included for rendering during packaging. No runtime or performance validation is claimed. The source checkout remained unmodified.
+
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
diff --git a/architecture/validation.md b/architecture/validation.md
new file mode 100644
index 0000000..644a104
--- /dev/null
+++ b/architecture/validation.md
@@ -0,0 +1,60 @@
+---
+layout: default
+title: "Validation and reproduction"
+permalink: /architecture/validation/
+description: "Source-pinned Civ13 architecture, UML diagrams, evidence boundaries and downloadable audit artifacts."
+image:
+ path: /public/img/architecture-overview.png
+ width: 1922
+ height: 573
+ alt: Civ13 architecture component overview
+---
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
+
+# Validation and reproducibility
+
+Source pin: 5bf351248de6050876fe5b53f91209a970cc5668. Audit date: 2026-10-20.
+
+## Executed successfully
+
+- Fresh master checkout pinned to the revision above; final git status is clean.
+- Python lexical inventory over all 1,462 tracked DM files; include closure and SHA-256 accounting generated without executing repository code.
+- Inventory checks: unique file paths, every discovered literal include exists, four declaration anchors, three call anchors and two excluded-feature anchors. See inventory/check-results.txt.
+- Python AST parsing of tracked Python support files: zero parse failures, 2,036 function/class declarations inventoried. This does not validate imports or behavior.
+- Runtime audit extraction: 93 research registrations, 99 prerequisite edges; no duplicate or unresolved prerequisite IDs. Process catalogue intentionally covers 37 directly included setup declarations, not every possible process instance.
+- 215 commit-pinned report source links checked for existing files and valid line ranges; zero errors.
+- PlantUML 1.2025.10 with local OpenJDK rendered 18 UML diagrams to SVG and PNG. Graphviz rendered two separately labeled graph views. All 20 SVG files parsed as XML with no renderer syntax-error output.
+- Reviewed all 18 PNG render layouts in a contact sheet and representative component, sequence and state diagrams at full size. No missing render or visibly clipped diagram was observed.
+- ReportLab generated the 19-page PDF atlas; pdfinfo confirms 19 pages, no embedded JavaScript. Each diagram retains a diagram-sized page to avoid shrinking labels onto fixed paper dimensions.
+
+## Not claimed
+
+No BYOND compiler, DreamChecker, DreamDaemon, live server, connected client, save round trip, gameplay assertion, performance benchmark, deployed bridge or external model was run. No exact compiler CFG, complete virtual dispatch solution, runtime path coverage, security certification or exhaustive behavioral verification is claimed.
+
+The initial local Mermaid/Chromium rendering route could not start in the available sandbox. It was not used to claim successful rendering. Equivalent PlantUML sources were rendered locally instead; Mermaid sources remain editable alternatives. Font-cache warnings did not prevent successful PlantUML/Graphviz output.
+
+## Render commands
+
+Use an official PlantUML 1.2025.10 jar, Java and Graphviz:
+
+ java -Djava.awt.headless=true -jar plantuml.jar -tsvg 'OUTPUT_ROOT/**/*.puml'
+ java -Djava.awt.headless=true -jar plantuml.jar -tpng 'OUTPUT_ROOT/**/*.puml'
+ dot -Tsvg INPUT.dot -o OUTPUT.svg
+ python tools/build_atlas.py OUTPUT_ROOT
+
+Inventory and report link checks:
+
+ python tools/build_inventory.py SOURCE_ROOT OUTPUT_ROOT/inventory
+ python tools/summarize_inventory.py SOURCE_ROOT OUTPUT_ROOT
+ python tools/check_inventory.py OUTPUT_ROOT/inventory
+ python tools/validate_artifacts.py SOURCE_ROOT OUTPUT_ROOT
+
+Runtime-specific extractor:
+
+ python runtime/build_runtime_artifacts.py --source SOURCE_ROOT --output OUTPUT_ROOT/runtime
+
+The scripts operate on source/artifacts only. Dependencies for PDF packaging are Pillow and ReportLab; core inventory uses Python standard library. No paid services or cloud rendering endpoints are needed.
+
+
+[Atlas home]({{ '/architecture/' | relative_url }}) · [Diagrams]({{ '/architecture/diagrams/' | relative_url }}) · [Audit]({{ '/architecture/audit/' | relative_url }}) · [Runtime]({{ '/architecture/runtime/' | relative_url }}) · [Persistence & services]({{ '/architecture/persistence/' | relative_url }})
diff --git a/public/architecture/2026-10-20/Civ13-architecture-UML-atlas.pdf b/public/architecture/2026-10-20/Civ13-architecture-UML-atlas.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..df9e58182f1fbe691d7786f9d91941b43a214116
GIT binary patch
literal 1409611
zcma&O+19Gu(k6Jmui^u-S5OcT=@bz}u>%AZQIXybLCul1Z=vd}&g)u>_3b}1cU5KO
z_}?|g>#Iy>8xb?&i6>ThElTY!jQykhfBql;`~UTq7QEB^tGd^}