From 51dfb9c66ca06b4ee7e2fb84f90a04e1b71d48e7 Mon Sep 17 00:00:00 2001
From: Alistair-Afton <AlistairDev@gmx.de>
Date: Fri, 18 Sep 2026 08:41:53 +0200
Subject: [PATCH] document job application heap and posting semantics

Verified on v0.53.16 via runtime sampling: the application binary heap
is a max-heap priority queue populated and drained within a single
job-assignment pass, job.flags.do_now adds ~20000000 to
job_applicationst.value, and dead postings are recycled.
---
 changelog.txt |  1 +
 df.job.xml    | 12 ++++++------
 2 files changed, 7 insertions(+), 6 deletions(-)

diff --git a/changelog.txt b/changelog.txt
index de360d67b0..aed7b8dbb5 100644
--- a/changelog.txt
+++ b/changelog.txt
@@ -21,6 +21,7 @@ Template for new versions:
 ## Structures
 - added support for overriding code generation for a specific type
 - added ``graphic_viewport_spatter_flag`` and related definitions
+- documented ``job_applicationst``/``job_postingst``/``job_flags.do_now`` semantics from job-assignment reverse engineering
 
 # 53.16-r1
 
diff --git a/df.job.xml b/df.job.xml
index 3160dcfd3d..efe303ff16 100644
--- a/df.job.xml
+++ b/df.job.xml
@@ -1484,7 +1484,7 @@
 
         <flag-bit name='on_break' original-name='COUNTS_AS_BREAK' comment='job displayed as On Break'/>
         <flag-bit name='dessource' original-name='DESSOURCE' comment='created from designation'/>
-        <flag-bit name='do_now' original-name='DO_ME_NOW'/>
+        <flag-bit name='do_now' original-name='DO_ME_NOW' comment='adds exactly 20000000 to job_applicationst.value for this job, outbidding nearly everything'/>
     </bitfield-type>
 
     <enum-type type-name='killjob_exception_type' base-type='int16_t'> bay12: KillJobExceptionType
@@ -1780,13 +1780,13 @@
         <int32_t name='idx' original-name='index' comment='equal to position in vector'/>
         <pointer type-name='job' name='job' original-name='job_ptr' comment='bad if dead flag is set'/>
         <bitfield base-type='uint32_t' type-name='job_posting_flag' name='flags' original-name='flag'/>
-        <int32_t name='rough_number_of_applications' comment='not saved'/>
+        <int32_t name='rough_number_of_applications' comment='not saved; incremented as units apply during assignment passes'/>
     </struct-type>
 
     <struct-type type-name='job_applicationst'>
         <pointer type-name='unit' name='applicant'/>
-        <int32_t name='posting_index'/>
-        <int32_t name='value'/>
+        <int32_t name='posting_index' comment='index into job_handlerst.postings'/>
+        <int32_t name='value' comment='bid score; the highest-valued application wins the posting. job.flags.do_now adds exactly 20000000'/>
     </struct-type>
 
     <struct-type type-name='job_application_binary_heapst'>
@@ -1796,9 +1796,9 @@
 
     <class-type type-name='job_handler' original-name='job_handlerst' custom-methods='true'>
         <df-linked-list name='list' original-name='global' type-name='job_list_link'/>
-        <stl-vector pointer-type='job_postingst' name='postings' original-name='posting' comment='entries never removed'/>
+        <stl-vector pointer-type='job_postingst' name='postings' original-name='posting' comment='entries never removed; dead entries are recycled for new jobs, so an index can change jobs between passes'/>
 
-        <compound type-name='job_application_binary_heapst' name='job_application_heap' comment='this appears to be a priority queue of some sort'/>
+        <compound type-name='job_application_binary_heapst' name='job_application_heap' comment='max-heap priority queue used by the job-assignment pass; populated and drained within a single pass, so usually empty when observed'/>
 
         <virtual-methods>
             <vmethod name='cancel_job' original-name='remove_job'><pointer type-name='job' name='ptr'/></vmethod>