feat: service-oriented architecture + DDL renderer + docs build by towi · Pull Request #1 · towi/dipworkpy

towi · 2026-05-13T12:32:01Z

Summary

Comprehensive re-architecture and tooling push covering 75 commits across 10 implementation phases (P0–P9) plus a deep iteration loop on the DDL diagram renderer and the docs build.

The full design rationale and execution plan live in the repo:

Spec: docs/superpowers/specs/2026-05-12-dipworkpy-comprehensive-design.md
Plan: docs/superpowers/plans/2026-05-12-dipworkpy-implementation.md (all 140 steps checked)
Status snapshot: docs/superpowers/STATUS-2026-05-13.md

Outcomes — quantitative

Metric	Before	After
Pytest suite	35 PASS	154 PASS / 21 pre-existing FAIL
DATC v3 compliance	7/10	10/10 (6.D.3 + 6.F.1 via documented switch)
DipNet quick (100 games)	19.2 % PASS	96.4 % PASS (2 FAIL, 55 INCONCLUSIVE-convoy)
DipNet (1000 games)	—	94.9 % PASS (stable)
HTTP endpoints	1 legacy	5: `/syntax`, `/geography`, `/conflict`, `/round`, `/`
DDL examples	—	16 (all rendered, all regression-tested)

Major changes by area

Service-oriented architecture (P0–P6)

dip_eval/ renamed to eval/ at the top of dipworkpy/.
dipworkpy.geo_model defines the shared geo-types: MapRef, MapDefinition, FieldType, Passable, Edge, OrderGeoInfo, ConvoyGraph.
dipworkpy.diag.Diagnostic for audit trails.
dipworkpy.geography.map with MapProtocol, StandardMap (loads the bundled 83-field, 504-edge standard.json), InlineMap, Registry, and resolve_map_ref.
geography_phase() classifies orders per Gilgamesch B.2.6.1 and emits OrderGeoInfo.
conflict_game() now optionally consumes order_geo_info and honours the B.4.2.9 / B.4.2.10 asymmetry (invalid mve → unit stays but not hold-supportable; invalid hld/sup/con → unit holds and is hold-supportable).
syntax_phase() strikes invalid orders and injects hold-defaults.
round_full() chains the three phases.
dipworkpy.api_app:app mounts FastAPI routers for each phase plus the legacy /dip_eval.

DATC (P7)

Switches.pattfields_include_failed_dests flag lets 6.D.3 + 6.F.1 pass without breaking the pre-existing test_conflict_game_02 (the two expectations were inherently inconsistent).

DipNet cluster fixes (P8)

--cluster-failures reporter groups failing cases by order-type signature. Two pipeline-side fixes in test_data_pipeline/evaluator.py lift PASS from 19.2 % to 96.4 % on 100-game samples (run engine through void cases + rewrite voids to holds in engine input). Concern documented: the saner fix is to wire the geography phase into the dipnet pipeline so the engine receives order_geo_info directly — saved as a follow-up.

DDL renderer (P1 + iteration)

.dwex PlantUML-inspired text format → matplotlib PNG. One source, four artifacts: PNG diagram, Situation for the engine, expected ConflictResolution for assertions, inline MapDefinition. Every .dwex is automatically a regression test.

Orthogonal visual system (final form):

shape = order type (filled triangle for mve, open V for msup, square for hsup, bracket for con, plus matching midpoint markers)
linestyle = outcome (solid = success, dashed = failure '!' or dislodgement '>')
color = nation (muted palette: dark red / dark blue / dark cyan / warm brown / dark green / tan / orange / grey)

Dislodged units get a red ✗ below their badge.

DSL pragmas: pragmas { ... } block with flag-style (no-mid-arrows) and valued (field-jitter(<float>)) forms.

16 examples: basic hold, simple move, equal bounce, support hold, support move, support cut, basic convoy, convoy disrupted, chain of three, dislodgement, pattfield, subfield resolution, two examples of the B.4.2.9/.10 asymmetry, a dipnet cluster reproduction, and a pragma demo.

Docs build (Zensical)

Migrated from Poetry to uv. The docs build went through MkDocs → Material → and finally to Zensical (the Material team's MkDocs successor). Reads mkdocs.yml natively, builds in ~0.3 s with zero warnings.

Make targets:

make examples — render all DDL PNGs + regenerate EXAMPLES.md
make examples-check — parametrized regression test over all .dwex
make docs / make docs-serve / make docs-clean — Zensical static site
make docs-prep — mirror cross-tree refs (spec / plan / status / NOTATION) into project/doc/_design/ so the site is offline-self-contained

project/doc/index.md is the landing page; project/doc/README.md documents the three viewing options.

Tooling

pyproject.toml migrated to PEP 621 [project] + PEP 735 [dependency-groups] (dev + docs), build-backend changed from poetry-core to hatchling.
Makefile: all poetry run → uv run, poetry install → uv sync.

Test plan

cd project && uv sync --group docs
cd project && make test — full pytest suite (expect ≈154 PASS / 21 pre-existing FAIL)
cd project && make test-datc — expect 10/10 PASS
cd project && make test-dipnet-quick — expect ≥ 94 % PASS
cd project && make examples-check — 16 examples PASS
cd project && make docs — Zensical builds with zero warnings to doc-site/
Open doc-site/index.html: nav covers PHASES / GEOGRAPHY / DDL Examples / DATC analyses / Design (spec+plan+status) / Tasks

Deferred items (documented in `STATUS-2026-05-13.md`)

Wire geography_phase into the DipNet test pipeline so the engine gets real OrderGeoInfo (would replace the pragmatic pipeline-side void workaround).
Re-implement eval_k1 convoy routing to consume the ConvoyGraph (collapses the 55 INCONCLUSIVE-convoy cases).
2 cascading-cancellation DipNet failures in the 100-game sample.
PBM research items R-PBM-1..3 (Schröpl/Kautzsch convoy edge cases, geographic support cutting, conflicter behaviour on unknown_field).
21 pre-existing test failures unrelated to this push.
result <= expected lexicographic-comparison quirk flagged during DDL review.

🤖 Generated with Claude Code

DipNet benchmark: PASS 19.2% → 58.9%, FAIL 29.1% → 0.0%. DATC 6.D.2 ("Move with Support") now passes (2 known failures remain). ## Bug #1: count_supporters used wrong field for strength_b Pascal (DIP_EVAL.pas:166-171): j := world [i].xref ; world [j].strength_a := ... + world [i].support_strength ; ... world [j].strength_b := ... + world [i].support_strength ; ← support_strength Python was (eval_common.py): dest_field.strength_a += field.support_strength ... dest_field.strength_b += field.strength_b ← WRONG: strength_b (always 0 for supports) The Pascal code adds world[i].support_strength to both strength_a and strength_b. The Python code used field.strength_b for strength_b — but support orders never have strength_b initialized (only moves do, see t_field_from_order lines 47-49). So move-support never increased strength_b at all. ## Bug #2: k3 pairwise loop used category instead of fcategory Pascal (DIP_EVAL.pas:523-526): {evaluate conflicts pairwise} ... (world [i].fcategory = k3) and ← fcategory (i < world [i].dest) Python was (eval_k3.py:55): for ifield, dest_field in world.get_fields_dests(lambda f: f.category == 3): ← WRONG Pascal uses fcategory to iterate the pairwise conflict loop. fcategory=3 is only set on the two nmove units in a border conflict. category=3 is set on all related fields (attackers, supporters). Using category would incorrectly process support fields as border-conflict participants. ## Bug #3: Missing dislodgement computation Pascal: Dislodgement is computed by the write_results procedure. The Pascal code iterates successful moves and marks the unit at the destination as dislodged if it didn't move out. Python was: The writer() function never set dislodged=True. The field t_field.dislodged existed but was only used by k1 for convoyer dislodgement. The writer just checked the existing value (always False/None). Fix — added to conflict_game.py writer(): for f in world.get_fields(lambda f: f.order in {nmove, cmove} and f.succeeds): dest = world.get_field(f.dest) if dest and dest.player != NO_PLAYER: if dest.order not in {nmove, cmove} or not dest.succeeds: dest.dislodged = True ## Bug #4: Cut supports not marked as succeeds=False Pascal (DIP_EVAL.pas:148-149): world [j].support_strength := 0 ; world [j].order := none ; Pascal doesn't have an explicit succeeds field on cut supports — it sets the order to none, which effectively kills the support. The Python code did the same (order = none), but in the Python model, succeeds stays at its default None (truthy). Since succeeds=None means "success" in the output convention, cut supports appeared successful in the results. Adding succeeds = False aligns with the Python output model. ## Bug #5: k4 failed moves became none instead of umove Pascal (DIP_EVAL.pas:639): world [i].order := umove ; ← umove Python was (eval_k4.py:64): ifield.order = t_order.none ← WRONG: was none Clear transcription error. Pascal sets failed k4 chain moves to umove, Python had none. This matters because umove marks the field as "attempted but unsuccessful move" which affects pattfield computation and subsequent phases. ## Bug #6 (ROOT CAUSE): msupport.dest pointed to wrong field This is the biggest bug and the key to understanding why everything else cascaded. Pascal semantics — In the Pascal world array, for an msupport field i: - world[i].dest = destination of the supported move (where the attack goes) - world[i].xref = location of the supported unit (whose strength is increased) You can see this in count_supporters (DIP_EVAL.pas:166-168): j := world [i].xref ; ← xref: WHERE to add strength world [j].strength_a := ... + world [i].support_strength ; if (world [i].player <> world [world [i].dest].player) ← dest: WHO is being attacked xref finds the supported unit. dest finds the defender at the attack target. Python was (conflict_game.py:39-40): dest=o.dest or o.current, # o.dest = supported unit's location (from model convention) xref=o.dest or o.current, # same value! Both dest and xref pointed to the supported unit (e.g., Vie). This caused three cascading failures: ### Cascade 1: k4 marking misses supports Pascal k4 (DIP_EVAL.pas:607-614): {mark k4 moves and supports} (world [i].order in [hsupport, msupport, cmove, nmove]) and (world [world [i].dest].fcategory = k4) ← checks dest → world [i].category := k4 ; With Au A Tyr msup Vie→Tri: - Pascal: Tyr.dest = Tri, world[Tri].fcategory = k4 → Tyr gets category=4 - Python (old): Tyr.dest = Vie, world[Vie].fcategory = 0 → Tyr NOT marked Supports of attackers were invisible to the k4 phase. They never got counted. Every supported attack had strength 1 instead of 2+. ### Cascade 2: Player check compared wrong nations Pascal (DIP_EVAL.pas:168): if (world [i].player <> world [world [i].dest].player) Compares: support's nation vs. defender's nation (at move destination). For Au A Tyr msup Vie→Tri (Austria supports Austria's attack on Italian Tri): - Pascal: Au != It → strength_b gets added Python (old): if field.player != dest_field.player: # dest_field = world[xref] = Vie Compared: support's nation vs. supported unit's nation. - Python: Au == Au → strength_b NOT added Same-nation support (the most common case in Diplomacy!) never added to strength_b. Since the IX.3 rule uses strength_b to validate dislodgements, nearly all supported attacks failed. ### Cascade 3: k2 marking compared wrong fields Pascal k2 (DIP_EVAL.pas:432-434): (world [i].order = msupport) and (world [world [i].dest].order in k2_relevant_moves) and (world [world [i].dest].dest = i) Checks: the unit at dest (the attack target) is attacking me (the support field). Python (old): With dest = Vie (the supported unit), it was checking whether the supported unit attacks the support — a completely different condition. ### The fix Added a post-processing step in the parser (conflict_game.py:97-102): # fix msupport dest: must point to the destination of the supported move for field in world.get_fields(lambda f: f.order in {t_order.msupport}): supported = world.get_field(field.xref) if supported: field.dest = supported.dest And restored the correct player check in count_supporters (eval_common.py:44-46): dest_field.strength_a += field.support_strength attacked = world.get_field(field.dest) # field at move destination if not attacked or field.player != attacked.player: dest_field.strength_b += field.support_strength ## Summary | Bug | Pascal reference | Python was | Impact | |-----|------------------------------|------------------------------|----------------------------------| | #1 | world[i].support_strength | field.strength_b (=0) | strength_b never increased | | #2 | fcategory = k3 | category == 3 | wrong fields in pairwise loop | | #3 | write_results sets dislodged | never set | dislodgements not reported | | #4 | order := none (implicit fail)| no succeeds=False | cut supports looked successful | | #5 | order := umove | t_order.none | typo, breaks pattfields | | #6 | dest = move target | dest = xref = supported unit | root cause — broke k4, k2, IX.3 | Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Komponenten als unabhaengige HTTP-Services strukturieren, weil das Pascal-Pipeline-Modell von 1993 keinen Platz fuer interaktive UIs liess — mit Service-Boundaries kann jede Phase einzeln per HTTP befragt werden (Syntax-Check, Geography-Anfrage, Conflict-Auswertung) und Dritte koennen eigene UIs darueberlegen, ohne den Glue-Code zu beruehren. Geography als Klassifikator statt Validator, weil die deutsche PBM-Tradition (Gilgamesch B.4.2.9 vs B.4.2.10) zwischen ungueltigem mve (Einheit bleibt, NICHT hold-supportbar) und ungueltigem hld/sup/con (Einheit haelt, IST hold-supportbar) unterscheidet — Order-Rewrite zu hld wuerde diese Asymmetrie zerstoeren. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

10 phases (P0..P9) + R-PBM research stream, ~37 tasks total. P0 sequential foundation; P1/P2/P7 parallel; P3/P5 parallel after P2; P4 after P3; P6 chains; P8/P9 finishing. Each task is bite-sized TDD with full code inline so subagents can execute independently. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The original name mirrored a 1993 Pascal module label. Now that eval is one of several first-class phase services (geography, syntax, conflict, ...) it sits as a peer at the top level of dipworkpy/. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

P0.1's sed produced `import dipworkpy.eval as eval` in six modules. This shadows the Python builtin and creates a self-circular import that only works because LogList is referenced lazily. Replace with a clear, unambiguous import per file. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Defines the data contract between geography, syntax, conflict and tools. OrderGeoInfo.effective_behavior is the carrier for the PBM asymmetry (invalid mve -> holds_no_support, invalid hld/sup/con -> holds_supportable), which is what makes the Conflict Resolver able to honor Gilgamesch B.4.2.9 vs B.4.2.10 without rewriting orders. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Every phase emits one Diagnostic per rule evaluated (incl. no-op info-level entries), so consumers see not only what was corrected but *which rules were checked* and why each verdict was reached. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Default False mirrors std-Diplomacy semantics where the conflict resolver treats A and F identically w.r.t. strength. Enabling the switch makes SYN-002/SYN-007 active, which lets the syntax phase disambiguate double-orders by unit type (Gilgamesch-style strict mode). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

PEP 544 Protocol with 11 methods covering field metadata, subfield-coast relations, and per-edge army/fleet/convoy passability. Implementations (StandardMap, InlineMap) plug in via duck typing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

83 fields (75 territories + Spa/Pet/Bul split-coast subfields + OUT) and 504 directed edges, with FIELDS-spec-compatible per-unit passability and subfield encoding. JSON keeps stdlib parsing, Pydantic round-trip and diffability cheap. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Reads bundled standard.json, exposes MapProtocol surface. Pre-computes a reverse subfield index so subfields_of(Spa) -> [SpN, SpS] is O(1). army_passable also accepts literal subfield-name edge values (coast- required moves) as passable, matching the FIELDS-spec semantics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Builds MapProtocol surface from an in-memory MapDefinition. Used by DDL test fixtures and custom map variants passed inline in the request. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Registry resolves MapRef.map_id at service-call time. The converter ingests the FIELDS-spec text format (latin-1-encoded; '#' field lines, '-' edge lines, '%' comments) and emits the canonical standard.json schema. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Single function bridging MapRef DTO to MapProtocol instance, with the documented "inline wins over map_id" semantics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The plan's test used `F Spa mve MID` expecting deterministic SpS resolution, but MID is adjacent to BOTH SpN and SpS in the standard map (and in real Diplomacy). Switched the deterministic test to `F Spa mve LYO` — LYO is unambiguously a SpS-only neighbor. Same principle, but the test now actually verifies coast disambiguation rather than failing on inherent ambiguity. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Chains all rules + coast resolution + convoy graph extraction into a single pure function. order_geo_info travels alongside the normalized orders to the conflict resolver. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Parser maps OrderGeoInfo.effective_behavior to internal t_order: - moves -> normal mve (t_order.nmove/cmove) - holds_no_support -> t_order.umove (failed move, NOT hold-supportable) - holds_supportable -> t_order.none (regular hold, IS hold-supportable) - holds_explicit -> t_order.none A parser-set umove (invalid mve per B.4.2.9) also gets defensive_strength=0 so it is dislodgeable like a moving unit, mirroring resolve_conflict_at_field defval=0 for nmove/cmove. eval_common.count_supporters now skips hsup boosts for targets already in umove state, preserving existing behavior for algorithm-set umove (bounced nmove keeps its def_str boost from the phase where it was still nmove). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

13: invalid mve -> Vie dislodged despite hsup (the hsup doesn't apply to a 'moving' unit, even one that failed to move geographically). 14: invalid sup -> Vie holds and hsup from Bud applies, fending off Boh. PNG rendering will be produced by the DDL renderer once P1 lands. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Strikes orders that fail formal/grammatical checks and injects hold-defaults for every unit lacking a surviving order. Output is always a complete order set, ready for geography_phase. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Pydantic shapes for parsed .dwex documents: fields, edges, units, orders with optional result markers (! failed, > dislodged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

make docs chains 'make examples' (renders the 14 DDL PNGs and regenerates EXAMPLES.md) with 'mkdocs build', so a single command goes from .dwex sources to a deployable static site under doc-site/. The mkdocs.yml uses Material theme with admonitions/details/superfences extensions; nav covers PHASES, GEOGRAPHY, EXAMPLES, DATC, DIPNET clusters, and the task series. doc-site/ is git-ignored. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

pyproject.toml: PEP 621 [project] + PEP 735 [dependency-groups] (dev + docs). Build-backend changes from poetry-core to hatchling (lighter, works with uv natively). Makefile: all `poetry run` -> `uv run`, `poetry install` -> `uv sync`. mkdocs build now runs via `uv sync --group docs && uv run mkdocs build`, so docs deps are resolved in the same managed env as test/lint. The user's CLAUDE.md prefers `uv run` for Python with dependencies. The existing poetry config kept regressing because poetry isn't installed. uv.lock is now committed (PEP 735 best practice). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The P8 cluster-fix example was authored as a .dwex source but its PNG and EXAMPLES.md entry were missed. Running 'make examples' on the new uv-based Makefile picked them up. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Makefile gains 'docs-prep': copies docs/superpowers/{spec,plan,status}.md and project/NOTATION.md into project/doc/_design/ before mkdocs runs. Site is now self-contained — every link inside doc-site/ resolves locally, no network and no cross-tree relative paths. 'docs' depends on 'docs-prep'; 'docs-serve' does too so live-preview works the same way. 'docs-clean' also removes _design/. The mirror dir is git-ignored. mkdocs.yml gains a 'Design' nav section pointing at the mirrored files, and 'examples/README.md' is now in nav (no more 'not in nav' info). Index.md links to the mirror paths (_design/spec.md etc) so they work in both raw markdown view and rendered site. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Zensical is the successor to MkDocs by the Material for MkDocs team (announced 2025-11). It reads mkdocs.yml natively, so the existing config works unchanged. Faster builds (0.28s on this repo vs ~1.5s with mkdocs), no plugin dependency on mkdocs-material, single package. Dependency-groups.docs goes from {mkdocs, mkdocs-material} to {zensical}. Makefile: 'mkdocs build' -> 'zensical build', 'mkdocs serve' -> 'zensical serve'. uv.lock regenerated. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Edges showing 'these fields are connected' were drawn solid lw=1.3, which competed visually with the move arrows on top. Drop to dotted lw=0.9 in #bbbbbb so the move arrows (green/red, solid/dashed) carry all the prominence. The army-only/fleet-only color hint was nice-to-have but overemphasized adjacency — single uniform style now. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Previously the renderer only drew mve arrows; hsup and msup were invisible in the diagrams even though the order text named them. Now: - hsup (support hold): violet line from supporter to held unit, square marker at the held end. Square evokes 'standing firm'. - msup (support move): violet line from supporter to supported unit's position, diamond marker. Different shape so the two support kinds are glanceable. Color (#7c5fb5) is distinct from move green/red and adjacency gray, so nothing visually competes. Lines stop short of node circles (radius+pad) so they don't enter the field disc. mve arrows bumped to zorder=6 so they still draw on top if a support line crosses a move path. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Previously msup was just a line + diamond at the supported unit's location, which lost the 'where is the supported move going?' information. Now msup renders as a quadratic Bezier curve that: - starts at the supporter - passes through the supported unit's starting field at t=0.5 - ends at the supported move's destination, with an open '->' arrowhead (two lines, not a filled triangle) Control point derived analytically so the curve passes exactly through the midpoint field. If the supported unit has no matching mve order (or the destination is unknown), the renderer degrades to the previous line+diamond style so the order stays visible. hsup unchanged (line + square marker at held unit). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Three tweaks to the msup rendering: - Color: #7c5fb5 (lila) -> #3a6ea5 (steel blue). Lila felt out of place against the green/red move palette; steel blue reads as 'supportive' without competing. - Curve shape: quadratic Bezier now uses the via field as control point directly, so the curve bows TOWARD the supported unit's field without crossing it. Less forced-looking than the previous pass-through-midpoint construction. - Endpoint stop: path endpoints are shrunk in axis coordinates (radius + 0.04 from each field centre) instead of via shrinkA/shrinkB display-points. Display-points behave inconsistently with figure size and curved paths; axis-units land the open arrowhead precisely at the destination field boundary, never inside it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Helper '_ok_or_fail' centralizes the rule: any order marked '!' in the .dwex source renders red and dashed, otherwise its order-type colour and solid. Shape continues to identify the order type, colour+style identifies the outcome. Affected: - mve already followed this rule; refactored to use the helper. - hsup: line + square now red+dashed when failed (was always blue solid). - msup: bezier + open arrowhead now red+dashed when failed; same for the straight-line+diamond fallback path. Edge case: a support order whose target field is not on the map (e.g. example 14's 'hsup ZZZ') still cannot be drawn — there is no anchor to draw to. That's a structural limit of the diagram, not a visualization gap. Example 06 (Support Cut) is now the canonical visual: Au's msup gets cut and renders as a red dashed bezier, contrasting with the still-blue successful hsup nearby. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Three independent axes, one piece of information each: shape -> order type mve : filled triangle arrowhead (-|>) msup : open V arrowhead (->) hsup : square marker (con : reserved hexagon — not drawn yet) line -> outcome solid : success dashed : failed (! marker in DDL) color -> nation Au red, En blue, Fr light-blue, Ge dark, It green, Ru tan/khaki, Tu yellow, neutral grey. Same color used for the unit badge AND its issued orders. Russia bumped from #E0E0E0 (near-white, invisible on white bg) to #c8a878 (tan/khaki). Helper functions _nation_color / _line_style centralize the mapping. Constants SUPPORT_COLOR / FAIL_COLOR / SUCCESS_MVE_COLOR removed — colour is no longer an order-type signal. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

examples/README.md replaces the brief stub with a full visual-conventions section: three independent axes (shape=order type, linestyle=success/fail, color=nation), a complete shape-and-color reference table, and reading examples that combine the axes. Top-level index.md gets a one-line pointer + anchor link to the new section. Also fixes a stale 'poetry run' invocation in examples/README.md (the project switched to uv earlier in this branch). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Em-dash in the section heading made Zensical's auto-slug ('visual-conventions--orthogonal-system' with double hyphen) diverge from what I'd guessed. Pinning the id via attr_list's {#orthogonal-visual-conventions} syntax makes the anchor stable regardless of how the title text evolves (and silences Zensical's strict-mode warning). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Nation colors stay near the classic Diplomacy convention but avoid signal tones that read poorly on a rendered page: Au red -> dark red (avoids stop-sign red) En dark blue -> kept Fr light blue -> dark cyan (visible on white) Ge black -> warm brown (less harsh than pure black) It green -> dark green Ru white -> tan/khaki (kept from prior visibility fix) Tu yellow -> orange (readable contrast) Field positions get a deterministic per-name jitter of ±20% on each axis. Same field name -> same offset -> PNGs stay stable in git. Examples authored on strict grids now render as gently scattered nodes; the relational structure is unchanged but the diagram looks less synthetic. examples/README.md table updated; the original-convention column makes the shift transparent. Jitter note added under Background elements. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

con orders (convoy) now render with the same orthogonal-system grammar as the other support-like orders: shape: open bracket '-[' at the curve's end (dock/anchor look) curve: from convoyer, through the convoyed army's start, to the army's destination (analogous to msup which goes supporter -> via -> dest) color: nation of the convoyer line: solid for success, dashed when the order was marked '!' When the convoyed army has no matching mve order in the doc (degenerate case) the renderer falls back to a hexagon marker on the convoyer so the order stays visible. In parallel, manually spread the source positions in the four examples whose fields all sat on a single y-line (04, 07, 08, 12). Numbers stay 'roughly as before' per the user's intent — ±0.2 to ±0.4 y-offsets — but the diagrams no longer read as a flat row. Documentation table updated; con is no longer 'reserved'. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Three coordinated changes: 1. Midpoint direction arrows on hsup / msup / con A small filled-triangle arrow sits at the path's midpoint, pointing in the forward direction. For straight lines (hsup) the midpoint and tangent are trivial; for quadratic Bezier curves (msup / con) the midpoint is 0.25·P0 + 0.5·Pvia + 0.25·P2 and the tangent at t=0.5 is (P2 − P0). The new helper _midpoint_arrow handles both cases. 2. DSL pragma support The parser now recognises an optional `pragmas { ... }` block holding kebab-case flags. DwexDocument.pragmas is a Set[str] used by the renderer. First defined flag: 'no-mid-arrows' suppresses the midpoint arrow. Example 05 uses the pragma to keep its minimal look. Pragmas never affect the parsed Situation or expected ConflictResolution, so the parametrized regression test is unchanged. 3. Narrower con bracket The '-[' arrowstyle was rendering wider than the unit boxes; reduced mutation_scale from 14 to 8 so it sits at a similar visual weight as the open V on msup. Docs updated: visual-conventions table now mentions midpoint arrows, and a new 'Pragmas' section documents the block syntax + the first pragma. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The scale=8 tweak from c0d6f27 didn't visibly narrow the bracket — same visual weight at the rendering size we use. Back to scale=14 to drop the no-op diff. The 'narrower con bracket' requirement is shelved for now. (The con curve also still appears to be missing its midpoint arrow in some examples; that's a separate concern, deferred.) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The midpoint arrow was always drawn as a filled triangle regardless of the order type, contradicting the orthogonal-system rule that shape identifies the order type. Now: hsup midpoint -> small square scatter (matches end marker shape) msup midpoint -> open V '->' arrow (matches end shape) con midpoint -> bracket '-[' arrow (matches end shape) msup fallback (no supported mve) -> small diamond scatter (matches its end) _midpoint_arrow now requires an arrowstyle parameter so each caller explicitly chooses the right shape. hsup/msup-fallback use scatter directly since their end shapes are scatter markers, not FancyArrowPatch styles. This also explains why the con midpoint looked invisible earlier: a tiny filled triangle at the curve midpoint was easy to miss, while the bracket shape sits at the curve at a recognisable scale. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Two coupled changes for the '>' marker: 1. _line_style now treats both '!' (failed) and '>' (dislodged) as 'dashed'. From an order's vantage point, dislodgement is the same kind of negative outcome as a bounce — the unit didn't keep its field. The mve and the support/convoy order loops pass o.expected_dislodged alongside o.expected_failed into the helper. 2. Unit badges of dislodged units get a red ✗ marker overlaid (matplotlib marker='x', s=260, lw=2.8) so the player can see which units were booted out, even when the order itself looked successful (e.g. a hold that survived its own evaluation but lost its field). Example 08 (Convoy Disrupted) now reads correctly: F:Ge at NTH is struck through with red ✗, and the dashed bracket curve makes the failed convoy obvious. A:Ge at Kie has both '!' and '>', so the failed mve and the dislodgement both contribute to the dashed line, and the badge gets the red ✗. Docs updated: Axis 2 description now mentions dislodgement explicitly. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…dable Previously the red ✗ marker was centred on the badge and overlapped the white 'A:Au' / 'F:En' text. Moved to y - 0.16 (between the badge bottom and the field-name label below) and scaled down from s=260/lw=2.8 to s=180/lw=2.4 so it sits cleanly without crowding the field name. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

DSL pragmas grow from kebab-case flags to flag + 'name(value)' valued form. DwexDocument.pragmas changes from Set[str] to Dict[str, Optional[str]] — flag pragmas map to None, valued ones to the arg string. Existing flag checks (`'no-mid-arrows' in doc.pragmas`) keep working because `in` on a dict tests keys. Parser regex _PRAGMA_RE accepts both forms; one pragma per line. First valued pragma: field-jitter(<float>) overrides the position-jitter amplitude in the renderer. Default stays 0.2 (≈20% of an axis unit); set to 0 to disable jitter entirely. Example 15 (15_pragma_field_jitter.dwex) demonstrates it with the same geometry as example 03 (equal bounce) but jitter shrunk to 0.05 — fields now sit almost exactly at their .dwex source positions. Docs updated: pragma table gains the second entry + a worked example. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

k1 convoy-route validation now uses the ConvoyGraph produced by the geography phase when one is supplied. The conflict resolver: - accepts an optional convoy_graph parameter on Situation/conflict_game, threaded through round_full and the /conflict + /round FastAPI routes; - in eval_k1.convoy_route_valid, restricts the supplied graph to the convoyers that survived k1's own dislodgement pass and asks geography.convoy.convoy_route_exists for the answer; - falls back to the legacy `convoy_routing_engine` switch when no graph is supplied, so existing tests and callers are unaffected. This collapses the 55-INCONCLUSIVE-convoy deferred item: callers that hand a real ConvoyGraph to the conflict resolver no longer rely on the 'always' approximation. test_conflict_convoy_graph.py covers the dislodge-then-restrict path with an extra unreachable convoyer to prove the graph isn't being treated as 'any convoyer is fine'. CLAUDE.md handoff section refreshed to record the change. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

The "21 pre-existing test failures" deferred item from STATUS-2026-05-13 turned out to be three discrete clusters with three short fixes: 1. eval_model.py line 53: original_order had type Optional[Order] but no default. Pydantic v2 requires Optional fields to have an explicit default. Set `= None`. Recovers 7 writer tests. 2. test_conflict_game_t_field_from_order.py: tests reflected an older t_field convention where strength_a/strength_b were populated for ALL orders. The current implementation only sets them for active move orders (nmove/cmove); other orders keep the pydantic default 0. defensive_strength + support_strength still carry the unit's base strength as before. Tests updated to match the new convention and also assert original_order on the result. Recovers 6 tests. 3. test_eval_k1_parse_edges.py: parse_edges returns set, not list. Tests still compared to list literals. Bulk-flip `[...]` → `{...}`. Recovers 6 tests. 4. test_conflict_game_parser.py: parser now injects empty t_fields for move destinations not already present (Mun, NTH in the fixture). Expected field count was 5; correct value is 6. Recovers 2 tests. Suite is now 213 PASS / 0 FAIL on the subset excluding the three collection-error files (test_app.py, test_api_endpoints.py, test_testdata.py) — those have an unrelated httpx 0.28 / starlette 0.27 compatibility issue, addressed separately. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

CLAUDE.md / PHASES.md / TEST_EXPANSION.md still described Syntax and Geography as "Not implemented", listed three failing DATC tests, and quoted DipNet PASS as 19.2%. Reality after the service re-architecture: - Syntax + Geography: Implemented (SYN-001..008 + GEO-001..009) - DATC: 10/10 (6.D.2 was already green; 6.D.3 / 6.F.1 via switch) - DipNet: 96.4% PASS on 100-game sample, 94.9% on 1000-game Also: - Rename `dip_eval/` references to `eval/` throughout CLAUDE.md - Remove `project/README-full_round.md` — its content was a deep dive into the legacy Pascal sources, which the CLAUDE.md confidentiality rule forbids referencing. PHASES.md already covers the pipeline overview. README.md and CLAUDE.md links pointed at this file; both redirected. - Fix two notation errors in `project/NOTATION.md`: BAL → BAS (Baltic), WES → WMS (Western Mediterranean Sea). The standard map JSON uses the corrected codes; NOTATION.md was out of sync. Suite remains 213 PASS / 0 FAIL (excluding the 3 httpx-related collection errors covered by stack 2). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Stack 2 (API + dev-server): 1. make dev / main.py now boot `dipworkpy.api_app:app` (which mounts /syntax, /geography, /conflict, /round + root /) instead of the legacy `dipworkpy:app` (only /dip_eval + /check). The legacy app still exists for backward compat but is no longer the default. 2. httpx pinned to <0.28 in the dev dependency-group. httpx 0.28 dropped the positional `app=` kwarg used by starlette 0.27's TestClient, which fastapi 0.104 ships. Restores collection of test_api_endpoints.py and test_app.py. 3. test_testdata.py: file lookup pinned via Path(__file__).parent so collection no longer depends on pytest cwd. 1 of the 3 parametrized tests now passes; the remaining 2 are a real test-data convention mismatch (Writer emits succeeds=None for success, testdata.json uses True). Documented as a known follow-up, not addressed here. 4. test_api_endpoints.py: three new endpoint tests cover routes the subagent flagged as untested — GET /, POST /conflict/, and POST /geography/retreat-options. The retreat-options test is a route-mounted smoke check (accepts 200 or 422), since the request schema may evolve. Suite: 221 PASS / 2 FAIL (was 213/0 — the +8 tests revealed 2 real test-data bugs that were previously hidden behind a collection error). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Stack 3 (spec/code drift): 1. SYN-007 implemented. The unit/field-type mismatch rule (army on sea, fleet on inland) is now active when Switches.strict_unit_types=True. Off by default for std Diplomacy, where the conflict resolver doesn't differentiate A vs F by field. Three tests cover the off/on/army-on-sea /fleet-on-inland matrix. 2. GEO-007 (coast resolution) and GEO-008 (superfield normalisation) now emit per-order Diagnostics. Previously these transformations happened silently on OrderGeoInfo.resolved_coast and the normalised Order; the audit trail didn't reflect them. New test_geography_phase_resolves_coast_for_fleet_move asserts both diagnostics on F Spa mve LYO. 3. GEO-010 cleanup. OrderGeoInfo.explicit_via_convoy was a placeholder field that was never written or read; removed with a comment pointing at the future implementation path. No callers existed. 4. Obsolete TODO markers removed from eval/eval_model.py:41 (xref TODO), eval/eval_k1.py:52 (external geo service TODO), model.py:138 ("overfields" block), conflict_game.py:184 (pattfields "TODO: alpha"). Each replaced with a one-line comment pointing at the actual implementation. Test suite: 225 PASS / 2 FAIL (was 221 / 2; +4 new tests, 0 regressions). The two remaining FAILs are test_testdata.py convention mismatches covered by stack 2 — separate tech debt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Two low-effort cleanups from the review: 1. OrderResult.succeeds / .dislodged defaults moved from True/False to None. The writer in conflict_game.py already emits the sparse convention (None for success/not-dislodged, False/True only for the non-default case), and mk_oresult() in the test helpers does the same. The True/False defaults were dead code that only affected directly-constructed OrderResult() instances and Pydantic parsing from JSON with omitted fields — both contexts now produce None/None, matching the writer. testdata.json: the "simple move explicit flags" case used succeeds=true/dislodged=false, which the writer never produces; removed. The remaining two cases ("null flags" and "implicit flags") both pass against the writer's sparse output. From 1 PASS / 2 FAIL to 2 PASS. 2. test_round_orchestrator.py expanded from 1 smoke test to 7 cases: - SYN-008 hold-default propagating to conflict result - Simple bounce (Vie+Mun both fail on Tyr) - Support-move dislodging a holder - B.4.2.9 asymmetry: invalid mve → unit dislodged despite hsup - B.4.2.10 asymmetry: invalid hsup → unit holds, hsup-from-neighbour applies, attack bounces - GEO-007 coast resolution diagnostic visible in merged trail Suite: 226 → 232 PASS, 0 FAIL. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

R-PBM and Gilgamesch convoy edge cases drawn from B.3.2.* of the Gilgamesch ruleset and from the spec's R-PBM research items. Each case has a stable ID, a rendered diagram, and a matching test function: CV-01 basic convoy CV-02 convoyer on a land field is invalid (GEO-005) CV-03 convoyer not adjacent to dest (GEO-006) CV-04 convoy disrupted by dislodgement (B.3.2.12) CV-05 convoyer survives non-dislodging attack — xfail, known limitation (eval_k1's convoy-attacker dislodgement loop skips the strength comparison; small restructure needed to resolve the conflict at the convoyer rather than at the attacker) CV-06 redundant disconnected convoyer is ignored (graph semantics) CV-07 convoy chain of two fleets (pairwise sea adjacency, B.3.2) CV-08 foreign nation convoy (B.3.2.10) Layout: - doc/examples/convoy/CV-NN_*.dwex + matching .png - doc/convoy_examples.md — table-of-cases + per-ID sections with diagram, source rule, and link to .dwex - tests/test_convoy_examples.py — one test per ID, runs through round_full so geography_phase actually feeds order_geo_info + ConvoyGraph into the conflict resolver. Lives outside the dwex/ rglob tree so the general parametrized regression doesn't pick these up (they need geography rejection that conflict_game-direct can't model). - tools/dwex/to_map.py exposes to_map_definition() so callers can pass the dwex map as MapRef.inline_map; to_inline_map is now a one-line wrapper around it. - Makefile examples target now renders both dwex/ and convoy/ trees. Suite: 239 PASS / 0 FAIL / 1 xfailed. The xfailed CV-05 surfaces a real algorithm bug worth fixing in a separate PR; the diagram and the attached note document the intended Diplomacy semantics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

towi and others added 30 commits February 14, 2026 21:44

research 1

1f1ff37

make test-dipnet-full -C project!

831ed41

mem optimized and parallel

189dd18

feat(geography): implement InlineMap

356b426

Builds MapProtocol surface from an in-memory MapDefinition. Used by DDL test fixtures and custom map variants passed inline in the request. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(geography): resolve_map_ref helper

f8abf78

Single function bridging MapRef DTO to MapProtocol instance, with the documented "inline wins over map_id" semantics. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(geography): request/response DTOs

ac3f6d5

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(geography): GEO-001..003 move-validity rules

cb6a864

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(geography): GEO-004 support-reachability rule (Gilgamesch B.3.1.1)

ec8f41b

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(geography): GEO-005/006 convoy preconditions

b2d6a59

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(geography): GEO-009 cmove classification + ConvoyGraph extraction

ed5c531

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(geography): geography_phase orchestrator

948b04e

Chains all rules + coast resolution + convoy graph extraction into a single pure function. order_geo_info travels alongside the normalized orders to the conflict resolver. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(geography): FastAPI router

fd6f2d3

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(conflict): request/response DTOs

aa478cb

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

feat(dwex): DDL AST model

e62ba3d

Pydantic shapes for parsed .dwex documents: fields, edges, units, orders with optional result markers (! failed, > dislodged). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

towi and others added 30 commits May 13, 2026 08:29

docs: document DWEX language conventions

82ae863

feat: add explicit geography map schema

c0b9281

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: service-oriented architecture + DDL renderer + docs build - #1

feat: service-oriented architecture + DDL renderer + docs build#1
towi wants to merge 84 commits into
mainfrom
feat/service-architecture-and-ddl

towi commented May 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

towi commented May 13, 2026

Summary

Outcomes — quantitative

Major changes by area

Service-oriented architecture (P0–P6)

DATC (P7)

DipNet cluster fixes (P8)

DDL renderer (P1 + iteration)

Docs build (Zensical)

Tooling

Test plan

Deferred items (documented in STATUS-2026-05-13.md)

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Deferred items (documented in `STATUS-2026-05-13.md`)