Atomizer/hq/skills/atomizer-protocols/protocols/SYS_19_JOB_QUEUE.md

SYS_19 — Job Queue Protocol

Purpose

Defines how agents submit and monitor optimization jobs that execute on Windows (NX/Simcenter).

Architecture

Linux (Agents)                    Windows (NX/Simcenter)
/job-queue/                       C:\Atomizer\job-queue\
├── inbox/     ← results          ├── inbox/
├── outbox/    → jobs             ├── outbox/
└── archive/   (processed)        └── archive/

Syncthing keeps these directories in sync (5-30 second delay).

Submitting a Job

Study Builder creates job directory:

outbox/job-YYYYMMDD-HHMMSS-<name>/
├── job.json               # Job manifest (REQUIRED)
├── run_optimization.py    # The script to execute
├── atomizer_spec.json     # Study configuration (if applicable)
├── README.md              # Human-readable description
└── 1_setup/               # Model files
    ├── *.prt              # NX parts
    ├── *_i.prt            # Idealized parts
    ├── *.fem              # FEM files
    └── *.sim              # Simulation files

job.json Format

{
  "job_id": "job-20260210-143022-wfe",
  "created_at": "2026-02-10T14:30:22Z",
  "created_by": "study-builder",
  "project": "starspec-m1-wfe",
  "channel": "#starspec-m1-wfe",
  "type": "optimization",
  "script": "run_optimization.py",
  "args": ["--start"],
  "status": "submitted",
  "notify": {
    "on_complete": true,
    "on_fail": true
  }
}

Monitoring a Job

Agents check job status by reading job.json files:

• outbox/ → Submitted, waiting for sync
• After Antoine runs the script, results appear in inbox/

Status Values

Status	Meaning
submitted	Agent placed job in outbox
running	Antoine started execution
completed	Finished successfully
failed	Execution failed

Receiving Results

Results arrive in inbox/ with updated job.json and result files:

inbox/job-YYYYMMDD-HHMMSS-<name>/
├── job.json              # Updated status
├── 3_results/            # Output data
│   ├── study.db          # Optuna study database
│   ├── *.csv             # Result tables
│   └── *.png             # Generated plots
└── stdout.log            # Execution log

Post-Processing

1. Manager's heartbeat detects new results in inbox/
2. Manager notifies Post-Processor
3. Post-Processor analyzes results
4. Move processed job to archive/ with timestamp

Rules

1. Never modify files in inbox/ directly — copy first, then process
2. Always include job.json — it's the job's identity
3. Use descriptive names — job-20260210-143022-starspec-wfe not job-1
4. Include README.md — so Antoine knows what the job does at a glance
5. Relative paths only — no absolute Windows/Linux paths in scripts